Skip to main content

​
APIs the Reseller (Service Provider) Needs to Implement

The APIs the Reseller (Service Provider) needs to implement for the MarketONE integration are MarketONE CSP Adapter OpenAPIs. The APIs the Reseller (Service Provider) needs to deploy are as follows:

​
Notification

MarketONE invokes this endpoint to trigger notifications to the customer (for example: to provide Merchant Partner subscription redemption information, or a one-time password). Notification messages can be sent based on the customer communication preferences (such as delivery medium, time preference, and locale).
  • POST /v2/notification
Resellers (Service Providers) can add a gateway adapter endpoint in Partner Ecosystem Management to receive notifications from MarketONE.

​
Events

MarketONE generates subscription and Merchant partner subscription lifecycle change events. When adding webhooks in Partner Ecosystem Management, Resellers (Service Providers) can select the events and configure the endpoints in order to receive callbacks. These settings can be configured during onboarding and can be updated at a later point in time. MarketONE triggers the callbacks to the Reseller integration layer, thereby allowing Resellers to consume the events. Resellers can use the information for their business intelligence purposes, for sending notifications to their customers, or for other purposes. Subscription Events Note: A Reseller (Service Provider) only needs to make Subscription API calls if their deployment incorporates ​Commerce Engine​ (and optionally ​Storefront Gateway​).
  • POST /event/subscription
Merchant Partner Subscription Events
  • POST /event/partnerSubscription

​
Account Validation

Note: Resellers (Service Providers) only need to implement this API if their deployment leverages external components for subscription management. The purpose of this API is for Reseller to provide customer account details and confirm the customer’s eligibility to subscribe to the Merchant Partner subscription.
  • POST /v2/account/validate
Resellers (Service Providers) can add a gateway adapter endpoint in Partner Ecosystem Management for account validation.

​
Merchant-Initiated Update Validation

These APIs allow Resellers (Service Providers) to approve or decline product upgrades or downgrades. For example: when a customer wants to upgrade or downgrade their subscription, the Merchant sends a change approval request to MarketONE. MarketONE then sends a request to the Reseller. If the Reseller approves the change request, the Merchant can update the subscription. As a result, MarketONE will update the Merchant Partner subscription object with the new product ID. If the Reseller declines the change, no change is made and a decline response is sent.
  • POST /v2/subscription/{id}/update/validate (for Resellers using MarketONE with Commerce Engine and Storefront Gateway components)
  • POST /v2/entitlement/{id}/update/validate (for Resellers leveraging external components for subscription management)
Resellers (Service Providers) can add a gateway adapter endpoint in Partner Ecosystem Management for Merchant-initiated update validation. Resellers also have the option of turning on automatic approval of Merchant-initiated updates. Parent topic:Reseller (Service Provider) APIs

​
APIs Called for the Platform-Managed Flow

The following APIs need to be called for integrations using the Platform-Managed flow (that is, when reselling Merchant products).

​
Subscription

Note: A Reseller (Service Provider) only needs to make Subscription API calls if their deployment incorporates Commerce Engine (and optionally Storefront Gateway). Subscriptions allow you to bill an Account over time and/or on a recurring basis. A subscription ties an Account to a particular billing plan and set of purchased products (subscription items) that have been created.
  • GET /v2/subscriptions
  • GET /v2/subscriptions/{id}
  • POST /v2/subscriptions
  • POST /v2/subscriptions/{id}
  • POST /v2/subscriptions/{id}/actions/cancel

​
Accounts

The Account represents a Merchant’s customer. As such it can contain as much or as little information as you collect about the customers (people or organizations) to which you offer billing and subscriptions. Subscriptions and Transactions must belong to an Account - as such, Accounts will be required in MarketONE for billing. An Account can have any number of children accounts and may have up to one parent account. An Account owns the “on file” payment methods to be used by it in billing. Payment Methods can be created at the same time as an Account is created or updated, but when updating an existing Payment Method the Payment Method endpoint must be used.
  • GET /v2/accounts
  • GET /v2/accounts/{id}
  • POST /v2/accounts
  • POST /v2/accounts/{id}

​
Merchant Partner Subscription

PartnerSubscription is MarketONE’s representation of a customer’s subscription to a Merchant’s service. When a customer buys a Merchant’s product in a Reseller’s (Service Provider’s) store, a partnerSubscription object is created in MarketONE to represent the subscription entitlement. The Merchant and Reseller use the partnerSubscription resource to communicate. In API requests, the partnerSubscription object informs the Merchant about updates made by the Reseller to the subscription, and vice versa. The GET calls let you retrieve Partner subscriptions. You can use the POST call to trigger a new Partner provisioning sequence.
  • GET /v2/partnerSubscription
  • GET /v2/partnerSubscription/{id}
  • POST /v2/partnerSubscription/{id}/reprovision

​
Entitlement

Note: A Reseller (Service Provider) only needs to make Entitlement API requests if their deployment leverages external components for subscription management. The Entitlement APIs apply to the integration of external catalog and billing systems with MarketONE. The Entitlement APIs allow Resellers (Service Providers) to manage the subscription lifecycle of customers through their external systems of choice. With the Entitlement APIs, Resellers can create an entitlement (provision a user), retrieve an entitlement, update it, update entitlement metadata, pause the entitlement, resume it, and cancel it. The Reseller can also approve or decline product changes the Merchant initiates. This integration exists under the Platform-Managed flow. If a Reseller wants to use an external catalog or billing system, they must use POST /v1/entitlement to provision users instead of the GET or POST Subscriptions endpoint. Additionally, the Reseller must use the Entitlement APIs for any required user entitlement updates, pauses, resumptions, or terminations under this integration.
  • POST /v1/entitlement
  • GET /v1/entitlement
  • POST /v1/entitlement/{id}/pause
  • POST /v1/entitlement/{id}/resume
  • POST /v1/entitlement/{id}/terminate
  • POST /v1/entitlement/{id}/metadata/update
  • POST /v1/entitlement/{id}/product/update
Parent topic:Reseller (Service Provider) APIs

​
Guiding Principles

The following guiding principles are applicable across all of the entities:
  • Mobile or phone numbers sent by the BSS either in the response or request payload should follow the E.164 format.
  • The email address when exchanged from the BSS should follow the RFC 5322 format.
  • The currency code will follow the ISO4217 format.

​
OpenAPIs

Please refer to the MarketONE OpenAPIs and the MarketONE CSP Adapter OpenAPIs for request and response examples. Parent topic:Reseller (Service Provider) APIs