Get subscription details

Retrieve details for a NachoNacho subscription whenever you need to verify whether the buyer is still a paying customer. You can call this endpoint at login, once a month, or any other time required by your business logic. Use the NachoNacho subscription ID to fetch the subscription details.

The response shape depends on the flow the subscription belongs to, given by the type field:

PROVISIONING: subscription_payment holds the Stripe subscription object. For additional subscription fields, see the Stripe API documentation.
NACHO_PAY: there is no Stripe subscription, so subscription_payment is null. Use payment_source and can_be_charged to check that the buyer still has a payment source you can bill through POST /payments.

get/subscriptions/{subscriptionId}

Path parameters

subscriptionIdstring required

Example:cmmcoxge20001cnsppobu1anr

NachoNacho subscription ID (from POST /tokens/resolve response)

Response

Subscription details with user, company, and — for PROVISIONING subscriptions — Stripe subscription data

subscriptionIdstring

type'PROVISIONING' | 'NACHO_PAY'

Which flow this subscription belongs to. Determines whether subscription_payment or payment_source is populated.

createdinteger

NACHO_PAY only. Unix timestamp of when the NachoNacho subscription was created.

can_be_chargedboolean

NACHO_PAY only. True when the buyer has a payment source on file and has not canceled, meaning POST /payments will work.

status'active' | 'canceled'

NACHO_PAY only. canceled once the Buyer has ended the subscription. Cancellation is final: a canceled subscription can never be charged or reactivated.

canceled_atinteger nullable

NACHO_PAY only. Unix timestamp of when the Buyer canceled, or null if still active.

Example response

{
  "subscriptionId": "cmmcoxge20001cnsppobu1anr",
  "type": "NACHO_PAY",
  "created": 1785312000,
  "can_be_charged": true,
  "payment_source": {
    "id": "pm_1TzXfFBIVxOUngQDuTo9rYAB",
    "type": "card",
    "brand": "visa",
    "last4": "4242",
    "exp_month": 1,
    "exp_year": 2029
  },
  "user": {
    "id": "clxx123abc",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com"
  },
  "company": {
    "id": "clxx456def",
    "name": "Acme Inc"
  },
  "subscription_payment": {
    "id": "sub_1234567890",
    "object": "subscription",
    "collection_method": "charge_automatically",
    "currency": "usd",
    "customer": "cus_Na6dX7aXxi11N4",
    "invoice_settings": {
      "issuer": {
        "type": "self"
      }
    },
    "items": {
      "object": "list",
      "data": [
        {
          "id": "si_Na6dzxczY5fwHx",
          "object": "subscription_item",
          "plan": {
            "id": "price_1MowQULkdIwHu7ixraBm864M",
            "object": "plan",
            "active": true,
            "amount": 1000,
            "amount_decimal": "1000",
            "billing_scheme": "per_unit",
            "currency": "usd",
            "interval": "month",
            "interval_count": 1,
            "product": "prod_Na6dGcTsmU0I4R",
            "usage_type": "licensed"
          },
          "price": {
            "id": "price_1MowQULkdIwHu7ixraBm864M",
            "object": "price",
            "active": true,
            "billing_scheme": "per_unit",
            "currency": "usd",
            "product": "prod_Na6dGcTsmU0I4R",
            "recurring": {
              "interval": "month",
              "interval_count": 1,
              "usage_type": "licensed"
            },
            "tax_behavior": "unspecified",
            "type": "recurring",
            "unit_amount": 1000,
            "unit_amount_decimal": "1000"
          },
          "quantity": 1,
          "subscription": "sub_1MowQVLkdIwHu7ixeRlqHVzs"
        }
      ],
      "total_count": 1,
      "url": "/v1/subscription_items?subscription=sub_1MowQVLkdIwHu7ixeRlqHVzs"
    },
    "latest_invoice": "in_1MowQWLkdIwHu7ixuzkSPfKd",
    "payment_settings": {
      "save_default_payment_method": "off"
    },
    "status": "active",
    "trial_settings": {
      "end_behavior": {
        "missing_payment_method": "create_invoice"
      }
    }
  },
  "status": "active"
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.