Skip to main content
GET
/
external
/
subscriptions
/
{id}
/
expanded
Get subscription by ID with expanded data
curl --request GET \
  --url https://platform.runonatlas.com/external/subscriptions/{id}/expanded \
  --header 'x-api-key: <api-key>'
{
  "createdAt": "2021-01-01T00:00:00.000Z",
  "id": "atlas-internal-subscription-id-123",
  "startDate": "2021-01-01T00:00:00.000Z",
  "status": "active",
  "updatedAt": "2021-01-01T00:00:00.000Z",
  "allowCustomerChanges": true,
  "autoChargeInvoice": false,
  "autoSyncInvoice": true,
  "autoSendInvoice": true,
  "paymentGateway": "Stripe",
  "isTrial": false,
  "customerId": "atlas-internal-customer-id-123",
  "planId": "atlas-internal-plan-id-123",
  "merchantId": "atlas-internal-merchant-id-123",
  "plan": {
    "createdAt": "2021-01-01T00:00:00.000Z",
    "crossEnvironmentId": "plan-cross-env-id-123",
    "currency": "USD",
    "description": "A great plan for your needs",
    "id": "atlas-internal-plan-id-123",
    "isPrivate": false,
    "name": "Pro",
    "netTerms": "net30",
    "purchasable": true,
    "requestPricingText": "Contact us for pricing",
    "requestPricingUrl": "https://example.com/request-pricing",
    "status": "available",
    "updatedAt": "2021-01-01T00:00:00.000Z",
    "merchantId": "atlas-internal-merchant-id-123",
    "prices": [
      {
        "price": {
          "billingCadence": "monthly",
          "billingMode": "advance",
          "blockOverage": false,
          "createdAt": "2021-01-01T00:00:00.000Z",
          "entityType": "entitlement",
          "id": "atlas-internal-price-id-123",
          "name": "Pro Price",
          "priceType": "unit",
          "rules": {
            "quantity": 1,
            "price": 10
          },
          "status": "active",
          "usesCustomPricingUnit": false,
          "billableId": "atlas-internal-billable-id-123",
          "merchantId": "atlas-internal-merchant-id-123",
          "billable": {
            "createdAt": "2022-01-01T00:00:00.000Z",
            "updatedAt": "2022-01-01T00:00:00.000Z",
            "description": "Access our beautiful API",
            "eventQueryRules": {
              "conditions": [
                [
                  {
                    "key": "eventName",
                    "rule": "matches",
                    "value": "api-usage"
                  }
                ]
              ],
              "calculation": "sum",
              "overProperty": "data.quantity"
            },
            "id": "123",
            "name": "API Access",
            "status": "available",
            "billableType": "entitlement",
            "externalFlagId": "<string>",
            "includedLabel": "Included",
            "singleUnitLabel": "API call",
            "multipleUnitLabel": "API calls",
            "isPrivate": false,
            "showOnInvoice": true,
            "slug": "api-access",
            "hidden": false,
            "displayOrder": 0
          },
          "limit": 100,
          "maxUsage": 1000,
          "customPricingUnitId": "atlas-internal-custom-pricing-unit-id-123"
        }
      }
    ],
    "externalId": "external-plan-id-123",
    "basePlanPriceId": "atlas-internal-price-id-123",
    "basePlanPriceQuarterlyId": "atlas-internal-price-id-123",
    "basePlanPriceAnnuallyId": "atlas-internal-price-id-123",
    "basePlanPriceMonthlyStatus": "active",
    "basePlanPriceQuarterlyStatus": "active",
    "basePlanPriceAnnuallyStatus": "active",
    "basePlanPrice": {
      "billingCadence": "monthly",
      "billingMode": "advance",
      "blockOverage": false,
      "createdAt": "2021-01-01T00:00:00.000Z",
      "entityType": "entitlement",
      "id": "atlas-internal-price-id-123",
      "name": "Pro Price",
      "priceType": "unit",
      "rules": {
        "quantity": 1,
        "price": 10
      },
      "status": "active",
      "usesCustomPricingUnit": false,
      "billableId": "atlas-internal-billable-id-123",
      "merchantId": "atlas-internal-merchant-id-123",
      "billable": {
        "createdAt": "2022-01-01T00:00:00.000Z",
        "updatedAt": "2022-01-01T00:00:00.000Z",
        "description": "Access our beautiful API",
        "eventQueryRules": {
          "conditions": [
            [
              {
                "key": "eventName",
                "rule": "matches",
                "value": "api-usage"
              }
            ]
          ],
          "calculation": "sum",
          "overProperty": "data.quantity"
        },
        "id": "123",
        "name": "API Access",
        "status": "available",
        "billableType": "entitlement",
        "externalFlagId": "<string>",
        "includedLabel": "Included",
        "singleUnitLabel": "API call",
        "multipleUnitLabel": "API calls",
        "isPrivate": false,
        "showOnInvoice": true,
        "slug": "api-access",
        "hidden": false,
        "displayOrder": 0
      },
      "limit": 100,
      "maxUsage": 1000,
      "customPricingUnitId": "atlas-internal-custom-pricing-unit-id-123"
    },
    "basePlanPriceQuarterly": {
      "billingCadence": "monthly",
      "billingMode": "advance",
      "blockOverage": false,
      "createdAt": "2021-01-01T00:00:00.000Z",
      "entityType": "entitlement",
      "id": "atlas-internal-price-id-123",
      "name": "Pro Price",
      "priceType": "unit",
      "rules": {
        "quantity": 1,
        "price": 10
      },
      "status": "active",
      "usesCustomPricingUnit": false,
      "billableId": "atlas-internal-billable-id-123",
      "merchantId": "atlas-internal-merchant-id-123",
      "billable": {
        "createdAt": "2022-01-01T00:00:00.000Z",
        "updatedAt": "2022-01-01T00:00:00.000Z",
        "description": "Access our beautiful API",
        "eventQueryRules": {
          "conditions": [
            [
              {
                "key": "eventName",
                "rule": "matches",
                "value": "api-usage"
              }
            ]
          ],
          "calculation": "sum",
          "overProperty": "data.quantity"
        },
        "id": "123",
        "name": "API Access",
        "status": "available",
        "billableType": "entitlement",
        "externalFlagId": "<string>",
        "includedLabel": "Included",
        "singleUnitLabel": "API call",
        "multipleUnitLabel": "API calls",
        "isPrivate": false,
        "showOnInvoice": true,
        "slug": "api-access",
        "hidden": false,
        "displayOrder": 0
      },
      "limit": 100,
      "maxUsage": 1000,
      "customPricingUnitId": "atlas-internal-custom-pricing-unit-id-123"
    },
    "basePlanPriceAnnually": {
      "billingCadence": "monthly",
      "billingMode": "advance",
      "blockOverage": false,
      "createdAt": "2021-01-01T00:00:00.000Z",
      "entityType": "entitlement",
      "id": "atlas-internal-price-id-123",
      "name": "Pro Price",
      "priceType": "unit",
      "rules": {
        "quantity": 1,
        "price": 10
      },
      "status": "active",
      "usesCustomPricingUnit": false,
      "billableId": "atlas-internal-billable-id-123",
      "merchantId": "atlas-internal-merchant-id-123",
      "billable": {
        "createdAt": "2022-01-01T00:00:00.000Z",
        "updatedAt": "2022-01-01T00:00:00.000Z",
        "description": "Access our beautiful API",
        "eventQueryRules": {
          "conditions": [
            [
              {
                "key": "eventName",
                "rule": "matches",
                "value": "api-usage"
              }
            ]
          ],
          "calculation": "sum",
          "overProperty": "data.quantity"
        },
        "id": "123",
        "name": "API Access",
        "status": "available",
        "billableType": "entitlement",
        "externalFlagId": "<string>",
        "includedLabel": "Included",
        "singleUnitLabel": "API call",
        "multipleUnitLabel": "API calls",
        "isPrivate": false,
        "showOnInvoice": true,
        "slug": "api-access",
        "hidden": false,
        "displayOrder": 0
      },
      "limit": 100,
      "maxUsage": 1000,
      "customPricingUnitId": "atlas-internal-custom-pricing-unit-id-123"
    }
  },
  "billingCadence": "monthly",
  "currency": "USD",
  "endDate": "2021-12-31T00:00:00.000Z",
  "netTerms": "net30",
  "chargeForUsageBasedPricesDuringTrial": false
}

Authorizations

​
x-api-key
string
header
required

You can obtain this key from the Atlas dashboard. It must be of type secret

Path Parameters

​
id
string
required

The Atlas subscription ID

Minimum string length: 1
Example:

"atlas-internal-subscription-id-123"

Response

The subscription that has been retrieved with expanded plan data including prices and billables.

​
createdAt
string<date>
required

The date and time the subscription was created

Example:

"2021-01-01T00:00:00.000Z"

​
id
string
required

The Atlas subscription ID

Minimum string length: 1
Example:

"atlas-internal-subscription-id-123"

​
startDate
required

The start date of the subscription

Example:

"2021-01-01T00:00:00.000Z"

​
status
enum<string>
required

The status of the subscription

Available options:
draft,
pendingActivation,
active,
ended,
deleted
Example:

"active"

​
updatedAt
string<date>
required

The date and time the subscription was last updated

Example:

"2021-01-01T00:00:00.000Z"

​
allowCustomerChanges
boolean
required

Whether the customer can change the subscription, for example by cancelling it or creating another.

Example:

true

​
autoChargeInvoice
boolean
required

Whether to automatically charge invoices for this subscription to the associated payment gateway. Requires a valid Stripe connection. Only compatible with a Stripe payment gateway.

Example:

false

​
autoSyncInvoice
boolean
required

Whether to automatically sync invoices for this subscription to the associated payment gateway.

Example:

true

​
autoSendInvoice
boolean
required

Whether to automatically send invoices for this subscription from the associated payment gateway to the customers email address.

Example:

true

​
paymentGateway
enum<string> | null
required

The selected payment gateway for this subscription

Available options:
Stripe,
QuickBooks
Example:

"Stripe"

​
isTrial
boolean
required

Whether this subscription is a trial subscription

Example:

false

​
customerId
string
required

The Atlas customer ID

Minimum string length: 1
Example:

"atlas-internal-customer-id-123"

​
planId
string
required

The Atlas plan ID

Minimum string length: 1
Example:

"atlas-internal-plan-id-123"

​
merchantId
string
required

The Atlas merchant ID

Minimum string length: 1
Example:

"atlas-internal-merchant-id-123"

​
plan
object
required
​
billingCadence
enum<string> | null

The billing cadence for this subscription

Available options:
oneTime,
monthly,
quarterly,
annually
Example:

"monthly"

​
currency
enum<string> | null

The currency for this subscription

Available options:
USD
Example:

"USD"

​
endDate

The end date of the subscription

Example:

"2021-12-31T00:00:00.000Z"

​
netTerms
enum<string> | null

The net terms for this subscription; applies only if autoChargeInvoice is false. Determines the number of days after the invoice is issued before the payment is due.

Available options:
uponReceipt,
net30,
net60,
net90
Example:

"net30"

​
chargeForUsageBasedPricesDuringTrial
boolean | null

Whether to charge for usage-based prices during the trial period. Only applies if isTrial is true.

Example:

false