> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Customers, payments, subscriptions, invoices, and refunds.

Stripe is included in Archal's environment catalog. Use it in a sandbox for customers, payments, subscriptions, invoices, and refunds.

|                 |                                               |
| --------------- | --------------------------------------------- |
| Environment ID  | `stripe`                                      |
| Transport       | REST and MCP                                  |
| State           | JSON                                          |
| Contract        | `archal.environment-state.stripe` version `1` |
| Channel         | Preview                                       |
| Curated samples | 5                                             |

Preview means the environment is included for testing, but its upstream coverage is incomplete. Verify the operations your test depends on.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

<Note>
  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.
</Note>

* No real money movement and no guarantee beyond the published route surface.

## Curated starting states

List the five samples with `archal sample list stripe`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

<AccordionGroup>
  <Accordion title="Stripe small-business baseline">
    List one customer, then create and reset a second customer.

    **Sample ID:** `stripe.small-business.v1`

    **Category:** `minimal`

    **Starting state:** 2 records across `accounts`: 1, `customers`: 1

    **Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

    **First read:** `GET /v1/customers`. Expected result: HTTP 200.

    **Representative mutation:** `POST /v1/customers`. Expected result: HTTP 200, 201, 204.

    **Mutation input**

    ```json theme={null}
    {
      "description": "Annual platform plan started through assisted checkout.",
      "email": "billing@northstar-tools.example.test",
      "name": "Northstar Tools"
    }
    ```

    **Expected diff:** changes include `customers`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * No real money movement and no guarantee beyond the published route surface.

    **Start this sample**

    ```bash theme={null}
    archal sample show stripe.small-business.v1 --raw > archal-stripe-small-business.json
    archal state validate stripe archal-stripe-small-business.json
    archal session create stripe \
      --state stripe=archal-stripe-small-business.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show stripe.small-business.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/stripe/small-business/state.json` and is 3,859 bytes. The CLI verifies SHA-256 `604ba927f8368cd65442ef1b115aae63bb40faa71cc4c9fa1e15bfdd68d870dd` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Stripe checkout team">
    Exercise customers, products, prices, checkout sessions, setup intents, promotions, webhooks, and events.

    **Sample ID:** `stripe.checkout-team.v1`

    **Category:** `small-team`

    **Starting state:** 33 records across `accounts`: 1, `balanceTransactions`: 1, `charges`: 1, `checkoutSessions`: 3, `coupons`: 1, `customers`: 3, `events`: 8, `paymentIntents`: 1, `paymentMethods`: 2, `prices`: 3, `products`: 2, `promotionCodes`: 2, `setupIntents`: 2, `taxRates`: 2, `webhookEndpoints`: 1

    **Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

    **First read:** `GET /v1/customers`. Expected result: HTTP 200.

    **Representative mutation:** `POST /v1/customers`. Expected result: HTTP 200, 201, 204.

    **Mutation input**

    ```json theme={null}
    {
      "description": "Annual platform plan started through assisted checkout.",
      "email": "billing@northstar-tools.example.test",
      "name": "Northstar Tools"
    }
    ```

    **Expected diff:** changes include `customers`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * No real money movement and no guarantee beyond the published route surface.

    **Start this sample**

    ```bash theme={null}
    archal sample show stripe.checkout-team.v1 --raw > archal-stripe-checkout-team.json
    archal state validate stripe archal-stripe-checkout-team.json
    archal session create stripe \
      --state stripe=archal-stripe-checkout-team.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show stripe.checkout-team.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/stripe/checkout-team/state.json` and is 19,297 bytes. The CLI verifies SHA-256 `905e5404b08999ad007e107cfd218870a60f70acaad772267835b588b5801ea4` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Stripe populated subscription portfolio">
    Exercise subscription pagination plus test clocks, meters, usage, checkout sessions, events, and webhooks.

    **Sample ID:** `stripe.subscription-heavy.v1`

    **Category:** `populated`

    **Starting state:** 43 records across `accounts`: 1, `checkoutSessions`: 2, `coupons`: 2, `customers`: 5, `events`: 5, `meterEvents`: 3, `meters`: 1, `paymentMethods`: 4, `prices`: 4, `products`: 4, `subscriptions`: 6, `testClocks`: 1, `usageRecords`: 2, `usageRecordSummaries`: 1, `webhookEndpoints`: 2

    **Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

    **First read:** `GET /v1/subscriptions?limit=3`. Expected result: HTTP 200.

    **Representative mutation:** `POST /v1/customers`. Expected result: HTTP 200, 201, 204.

    **Mutation input**

    ```json theme={null}
    {
      "description": "Annual platform plan started through assisted checkout.",
      "email": "billing@northstar-tools.example.test",
      "name": "Northstar Tools"
    }
    ```

    **Expected diff:** changes include `customers`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * No real money movement and no guarantee beyond the published route surface.

    **Start this sample**

    ```bash theme={null}
    archal sample show stripe.subscription-heavy.v1 --raw > archal-stripe-subscription-heavy.json
    archal state validate stripe archal-stripe-subscription-heavy.json
    archal session create stripe \
      --state stripe=archal-stripe-subscription-heavy.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show stripe.subscription-heavy.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/stripe/subscription-heavy/state.json` and is 23,173 bytes. The CLI verifies SHA-256 `226972514779fbc815b84ed50a148c493dde83e5ab0feb6f39686f1b2ea015ea` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Stripe mixed card expiry">
    Read stored cards spanning past, near, and future expiry, then attach an unowned replacement card to the expired-card customer.

    **Sample ID:** `stripe.mixed-card-expiry.v1`

    **Category:** `edge-case`

    **Starting state:** 24 records across `accounts`: 1, `customers`: 5, `invoices`: 5, `paymentMethods`: 6, `prices`: 1, `products`: 1, `subscriptions`: 5

    **Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

    **First read:** `GET /v1/payment_methods?customer=cus_enterprise3&type=card&limit=10`. Expected result: HTTP 200.

    **Representative mutation:** `POST /v1/payment_methods/pm_meridian_replacement/attach`. Expected result: HTTP 200.

    **Mutation input**

    ```json theme={null}
    {
      "customer": "cus_enterprise3"
    }
    ```

    **Expected diff:** changes include `paymentMethods`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * No real money movement and no guarantee beyond the published route surface.

    **Start this sample**

    ```bash theme={null}
    archal sample show stripe.mixed-card-expiry.v1 --raw > archal-stripe-mixed-card-expiry.json
    archal state validate stripe archal-stripe-mixed-card-expiry.json
    archal session create stripe \
      --state stripe=archal-stripe-mixed-card-expiry.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show stripe.mixed-card-expiry.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/stripe/mixed-card-expiry/state.json` and is 16,866 bytes. The CLI verifies SHA-256 `abc4539b7f7b2f58f5ca8311755e23f6e949a8ac6c711ab7c90a66a19d7dec4e` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Stripe subscription lifecycle workflow">
    Inspect a successful subscription charge, issue a partial customer-requested refund, and verify the related charge and ledger state reset.

    **Sample ID:** `stripe.subscription-lifecycle.v1`

    **Category:** `workflow`

    **Starting state:** 82 records across `accounts`: 1, `balanceTransactions`: 5, `charges`: 12, `coupons`: 2, `customers`: 8, `invoiceItems`: 15, `invoices`: 10, `paymentMethods`: 8, `prices`: 6, `products`: 3, `promotionCodes`: 2, `refunds`: 1, `subscriptions`: 8, `webhookEndpoints`: 1

    **Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

    **First read:** `GET /v1/charges/ch_happy_apr`. Expected result: HTTP 200.

    **Representative mutation:** `POST /v1/refunds`. Expected result: HTTP 200.

    **Mutation input**

    ```json theme={null}
    {
      "amount": 4900,
      "charge": "ch_happy_apr",
      "reason": "requested_by_customer"
    }
    ```

    **Expected diff:** changes include `refunds`, `charges`, `balanceTransactions`, `events`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * No real money movement and no guarantee beyond the published route surface.

    **Start this sample**

    ```bash theme={null}
    archal sample show stripe.subscription-lifecycle.v1 --raw > archal-stripe-subscription-lifecycle.json
    archal state validate stripe archal-stripe-subscription-lifecycle.json
    archal session create stripe \
      --state stripe=archal-stripe-subscription-lifecycle.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show stripe.subscription-lifecycle.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/stripe/subscription-lifecycle/state.json` and is 53,820 bytes. The CLI verifies SHA-256 `cbfc7899bcff3e2cb2cf7b5c4c5553348817c92ede6e42f5fc3388e2195dd696` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>
</AccordionGroup>

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe stripe`, then validate the file before creating a sandbox:

```bash theme={null}
archal state validate stripe state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](/sandboxes/starting-state) before replacing state in an existing sandbox.