curl --request GET \
--url https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded \
--header 'x-api-key: <api-key>'import requests
url = "https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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",
"subscriptions": [
{
"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
}
],
"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": "john.doe@example.com",
"externalId": "external-customer-id-123",
"name": "John Doe",
"quickBooksId": "quickbooks-customer-id-123",
"stripeId": "stripe-customer-id-123"
}Get customer with expanded data
Get a customer by external ID with their active and upcoming subscriptions, custom pricing unit balances, and private plans.
curl --request GET \
--url https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded \
--header 'x-api-key: <api-key>'import requests
url = "https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://platform.runonatlas.com/external/customers/external-id/{externalId}/expanded")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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",
"subscriptions": [
{
"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
}
],
"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": "john.doe@example.com",
"externalId": "external-customer-id-123",
"name": "John Doe",
"quickBooksId": "quickbooks-customer-id-123",
"stripeId": "stripe-customer-id-123"
}Authorizations
You can obtain this key from the Atlas dashboard. It must be of type secret
Path Parameters
The external ID of the customer (e.g. the customer ID in your system)
1"external-customer-id-123"
Response
The customer that has been retrieved with their active and upcoming subscriptions, custom pricing unit balances, and private plans.
The date and time the customer was created
"2021-01-01T00:00:00.000Z"
The Atlas customer ID
1"atlas-internal-customer-id-123"
The date and time the customer was last updated
"2021-01-01T00:00:00.000Z"
The Atlas merchant ID
1"atlas-internal-merchant-id-123"
The subscriptions associated with the customer
Show child attributes
Show child attributes
The active subscriptions associated with the customer
Show child attributes
Show child attributes
The upcoming subscriptions associated with the customer
Show child attributes
Show child attributes
The conditional billable access associated with the customer
Show child attributes
Show child attributes
The custom pricing units associated with the customer
Show child attributes
Show child attributes
The private plans associated with the customer
Show child attributes
Show child attributes
Whether the customer is eligible for a trial subscription. Only returns true if the customer has no previous or current paid or trial subscriptions.
true
Billing address line 1
1"123 Main St"
Billing address line 2
1"Apt 1"
Billing city
1"Anytown"
Billing country
1"US"
Billing state
1"CA"
Billing zip code. Must be 5 digits or 5+4 format.
^\d{5}(-\d{4})?$"12345"
Shipping address line 1
1"123 Main St"
Shipping address line 2
1"Apt 1"
Shipping city
1"Anytown"
Shipping country
1"US"
Shipping state
1"CA"
Shipping zip code. Must be 5 digits or 5+4 format.
^\d{5}(-\d{4})?$"12345"
The email of the customer
1"john.doe@example.com"
The external ID of the customer (e.g. the customer ID in your system)
1"external-customer-id-123"
The name of the customer
1"John Doe"
The QuickBooks ID of the customer
1"quickbooks-customer-id-123"
The Stripe ID of the customer
1"stripe-customer-id-123"

