How to: connect with Arc XP Sales SDK and APIs on the web

We provide a set of APIs and SDK methods that allow you to connect your end users with our system. Before continue, see How-to Connect and log in with Arc XP Identity SDKs and APIs on the web to learn about the pros and const of using APIs vs SDKs, as well as the CDN endpoint.

Pros of using Arc XP Sales SDKs

• Our SDK provides easy access to several objects, and these objects contain useful information about the tenant (organization+site) settings and the current user account:
  • orders: contains all the payments for the user account. This information is obtained after calling Sales.getOrderHistory(), and keeps synchronized based on user activity (e.g. new purchases)
  • subscriptions: contains all the active subscriptions for the user account. This information is obtained after calling Sales.getAllSubscriptions() or Sales.getAllActiveSubscriptions(), and keeps synchronized based on user activity (e.g. new subscription is started).
  • paymentOptions: It stores all the payment options available for the tenant. This information is obtained after calling Sales.getPaymentOptions()

Using Sales from a public domain through APIs

All available public APIs are documented in our Open API documentation. You can identify these APIs by the presence of /sales/public/ in the endpoint URL. Some of these APIs do not require authentication. However, for those that do require authentication, you must pass a valid access_token (Authorization header). Ensure the access token is valid before making the API call.

Example: No authentication required

curl --location 'https://{ApiOrigin|CDN}/sales/public/v1/checkout/payment/options'

Example: Authentication required

curl --location 'https://{ApiOrigin|CDN}/sales/public/v1/subscription/allactive' \
--header 'Authorization: Bearer {access_token}'

For more information about the available APIs, see Arc XP Subscriptions APIs.

Using Sales from a public domain through the SDK

The Arc XP Identity SDK is published to NPM.

After you install npm, to install the Arc SDKs, execute the following command in your npm project:

npm i @arc-publishing/sdk-sales @arc-publishing/sdk-identity

Note

Identity SDK needs to be installed and initialized because Sales SDK depends on it. See How-to Connect and log in with Arc XP Identity SDKs and APIs on the web

After you have them installed, include the SDKs in your code:

import Sales from '@arc-publishing/sdk-sales';

To access the right API endpoints through the SDKs, specify an API Origin before calling any other SDK methods. You will need to pass Identity when initializing Sales, as several methods require authentication, and the authentication is handled by Identity.

import Identity from '@arc-publishing/sdk-identity';

Sales.options({
apiOrigin: '{your api origin or CDN here}'
Identity: Identity
});

For more information about the available SDK methods, see Arc XP Subscriptions SDKs.

Arc XP Sales SDKs and APIs

As mentioned earlier, our SDK methods serve as wrappers, making it easier for developers to interact with our APIs. The following table lists the Sales SDK methods and the corresponding APIs they wrap.

SDK Method	API
addItemToCart()	POST /sales/public/v1/cart/item
cancelSubscription()	PUT /sales/public/v1/subscription/${id}/cancel
clearCart()	DELETE /sales/public/v1/cart/clear
createOrder()	POST /sales/public/v1/checkout/order
finalizePayment()	PUT /sales/public/v1/checkout/order/${orderNumber}/payment/${paymentMethodID}
finalizePaymentPayU()	PUT /sales/public/v1/checkout/order/${orderNumber}/payment/${paymentMethodID}
finalizePaymentUpdate()	PUT /sales/public/v1/paymentmethod/${paymentID}/provider/${paymentMethodID}/finalize
getAddresses()	GET /sales/public/v1/checkout/addresses
getAllActiveSubscriptions()	GET /sales/public/v1/subscription/allactive
getAllSubscriptions()	GET /sales/public/v1/subscription/all
getCart()	GET /sales/public/v1/cart
getConfig()	GET /sales/public/v1/config
getOrderDetails()	GET /sales/public/v1/order/detail/${orderNumber}
getOrderHistory()	GET /sales/public/v1/order/history
getPaymentOptions()	GET /sales/public/v1/checkout/payment/options
getSubscriptionDetails()	GET /sales/public/v1/subscription/${id}/details
getSubscriptionSharingDetails()	GET /sales/public/v1/subscription/${id}/sharing
initializePayment()	GET /sales/public/v1/checkout/order/${orderNumber}/payment/${paymentMethodID}
initializePaymentUpdate()	PUT /sales/public/v1/paymentmethod/${paymentID}/provider/${paymentMethodID}
redeemAssociateInvitation()	POST /sales/public/v1/subscription/redeem
redeemEnterpriseSubscription()	POST /sales/public/v2/subscriptions/enterprise
redeemGiftSubscription()	POST /sales/public/v1/subscription/gift/redeem
removeItemFromCart()	DELETE /sales/public/v1/cart/item/${sku}
rescueSubscription()	PUT /sales/public/v1/subscription/${id}/rescue
setGiftRecipient()	PUT /sales/public/v1/subscription/gift/${redeemCode}
shareSubscription()	PUT /sales/public/v1/subscription/${id}/share
stopSharing()	PUT /sales/public/v1/subscription/${id}/stopshare
updateBillingAddress()	PUT /sales/public/v1/subscription/address