Skip to main content
POST
/
external
/
customers
Create customer with default plan subscription
curl --request POST \
  --url https://platform.runonatlas.com/external/customers \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "externalId": "external-customer-id-123",
  "billingAddress1": "123 Main St",
  "billingAddress2": "Apt 1",
  "billingCity": "Anytown",
  "billingCountry": "US",
  "billingState": "CA",
  "billingZipCode": "12345",
  "shippingAddress1": "123 Main St",
  "shippingAddress2": "Apt 1",
  "shippingCity": "Anytown",
  "shippingCountry": "US",
  "shippingState": "CA",
  "shippingZipCode": "12345",
  "email": "[email protected]",
  "name": "John Doe",
  "quickBooksId": "quickbooks-customer-id-123",
  "stripeId": "stripe-customer-id-123"
}
'
{
  "createdAt": "2021-01-01T00:00:00.000Z",
  "id": "atlas-internal-customer-id-123",
  "updatedAt": "2021-01-01T00:00:00.000Z",
  "merchantId": "atlas-internal-merchant-id-123",
  "activeSubscriptions": [
    {
      "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",
        "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",
          "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
    }
  ],
  "upcomingSubscriptions": [
    {
      "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",
        "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",
          "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
    }
  ],
  "conditionalBillableAccess": [
    {
      "access": true,
      "createdAt": "2021-01-01T00:00:00.000Z",
      "endDate": "2021-12-31T00:00:00.000Z",
      "id": "atlas-internal-conditional-billable-access-id-123",
      "invalidated": false,
      "startDate": "2021-01-01T00:00:00.000Z",
      "updatedAt": "2021-01-01T00:00:00.000Z",
      "billableId": "atlas-internal-billable-id-123",
      "customerId": "atlas-internal-customer-id-123",
      "merchantId": "atlas-internal-merchant-id-123",
      "subscriptionId": "atlas-internal-subscription-id-123",
      "currentUsage": 50
    }
  ],
  "customPricingUnits": [
    {
      "customPricingUnitId": "atlas-internal-custom-pricing-unit-id-123",
      "balance": 100
    }
  ],
  "customerPrivatePlans": [
    {
      "planId": "atlas-internal-plan-id-123"
    }
  ],
  "isEligibleForTrial": true,
  "billingAddress1": "123 Main St",
  "billingAddress2": "Apt 1",
  "billingCity": "Anytown",
  "billingCountry": "US",
  "billingState": "CA",
  "billingZipCode": "12345",
  "shippingAddress1": "123 Main St",
  "shippingAddress2": "Apt 1",
  "shippingCity": "Anytown",
  "shippingCountry": "US",
  "shippingState": "CA",
  "shippingZipCode": "12345",
  "email": "[email protected]",
  "externalId": "external-customer-id-123",
  "name": "John Doe",
  "quickBooksId": "quickbooks-customer-id-123",
  "stripeId": "stripe-customer-id-123"
}

Authorizations

​
x-api-key
string
header
required

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

Body

application/json
​
externalId
string
required

The external ID of the customer (e.g. the customer ID in your system)

Minimum string length: 1
Example:

"external-customer-id-123"

​
billingAddress1
string | null

Billing address line 1

Minimum string length: 1
Example:

"123 Main St"

​
billingAddress2
string | null

Billing address line 2

Minimum string length: 1
Example:

"Apt 1"

​
billingCity
string | null

Billing city

Minimum string length: 1
Example:

"Anytown"

​
billingCountry
string | null

Billing country

Minimum string length: 1
Example:

"US"

​
billingState
string | null

Billing state

Minimum string length: 1
Example:

"CA"

​
billingZipCode
string | null

Billing zip code. Must be 5 digits or 5+4 format.

Example:

"12345"

​
shippingAddress1
string | null

Shipping address line 1

Minimum string length: 1
Example:

"123 Main St"

​
shippingAddress2
string | null

Shipping address line 2

Minimum string length: 1
Example:

"Apt 1"

​
shippingCity
string | null

Shipping city

Minimum string length: 1
Example:

"Anytown"

​
shippingCountry
string | null

Shipping country

Minimum string length: 1
Example:

"US"

​
shippingState
string | null

Shipping state

Minimum string length: 1
Example:

"CA"

​
shippingZipCode
string | null

Shipping zip code. Must be 5 digits or 5+4 format.

Example:

"12345"

​
email
string<email> | null

The email of the customer

Minimum string length: 1
Example:

"[email protected]"

​
name
string | null

The name of the customer

Minimum string length: 1
Example:

"John Doe"

​
quickBooksId
string | null

The QuickBooks ID of the customer

Minimum string length: 1
Example:

"quickbooks-customer-id-123"

​
stripeId
string | null

The Stripe ID of the customer

Minimum string length: 1
Example:

"stripe-customer-id-123"

Response

The customer that has been created.

​
createdAt
string<date>
required

The date and time the customer was created

Example:

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

​
id
string
required

The Atlas customer ID

Minimum string length: 1
Example:

"atlas-internal-customer-id-123"

​
updatedAt
string<date>
required

The date and time the customer was last updated

Example:

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

​
merchantId
string
required

The Atlas merchant ID

Minimum string length: 1
Example:

"atlas-internal-merchant-id-123"

​
activeSubscriptions
object[]
required

The active subscriptions associated with the customer

​
upcomingSubscriptions
object[]
required

The upcoming subscriptions associated with the customer

​
conditionalBillableAccess
object[]
required

The conditional billable access associated with the customer

​
customPricingUnits
object[]
required

The custom pricing units associated with the customer

​
customerPrivatePlans
object[]
required

The private plans associated with the customer

​
isEligibleForTrial
boolean
required

Whether the customer is eligible for a trial subscription. Only returns true if the customer has no previous or current paid or trial subscriptions.

Example:

true

​
billingAddress1
string | null

Billing address line 1

Minimum string length: 1
Example:

"123 Main St"

​
billingAddress2
string | null

Billing address line 2

Minimum string length: 1
Example:

"Apt 1"

​
billingCity
string | null

Billing city

Minimum string length: 1
Example:

"Anytown"

​
billingCountry
string | null

Billing country

Minimum string length: 1
Example:

"US"

​
billingState
string | null

Billing state

Minimum string length: 1
Example:

"CA"

​
billingZipCode
string | null

Billing zip code. Must be 5 digits or 5+4 format.

Example:

"12345"

​
shippingAddress1
string | null

Shipping address line 1

Minimum string length: 1
Example:

"123 Main St"

​
shippingAddress2
string | null

Shipping address line 2

Minimum string length: 1
Example:

"Apt 1"

​
shippingCity
string | null

Shipping city

Minimum string length: 1
Example:

"Anytown"

​
shippingCountry
string | null

Shipping country

Minimum string length: 1
Example:

"US"

​
shippingState
string | null

Shipping state

Minimum string length: 1
Example:

"CA"

​
shippingZipCode
string | null

Shipping zip code. Must be 5 digits or 5+4 format.

Example:

"12345"

​
email
string<email> | null

The email of the customer

Minimum string length: 1
Example:

"[email protected]"

​
externalId
string | null

The external ID of the customer (e.g. the customer ID in your system)

Minimum string length: 1
Example:

"external-customer-id-123"

​
name
string | null

The name of the customer

Minimum string length: 1
Example:

"John Doe"

​
quickBooksId
string | null

The QuickBooks ID of the customer

Minimum string length: 1
Example:

"quickbooks-customer-id-123"

​
stripeId
string | null

The Stripe ID of the customer

Minimum string length: 1
Example:

"stripe-customer-id-123"