> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Key MarketONE Entities
Entities are key items that exist in the MarketONE UI and APIs. Entities can be roles, objects, or processes.
## Account
The account is the end customer account which is referenced in the Reseller (Service Provider) system. It holds the terms of a relationship for the Merchant services that has been entitled to a customer.
## Admin
The Admin is the specific individual associated with an organization. The Admin will be in charge of creating and maintaining the data entities associated with the Merchant.
## Agreement
The agreement is the official contract between a Reseller (Service Provider) and a Merchant organization that defines the terms of the settlement when a customer buys a Merchant's product.
## Entitlement
An entitlement represents ownership of a Merchant's product by an end customer in a Platform-managed flow. An entitlement is granted when an end customer purchases a subscription from the Reseller's (Service Provider's) digital store.
## Organization
The organization is the business group (or sub-entity), which can be either the Merchant or Reseller (Service Provider).
## Partnership
The partnership consists of a Reseller (Service Provider) and a Merchant that agree to do business together in MarketONE.
## Partner Subscription
A partner subscription (represented by the `partnerSubscription` object in the MarketONE OpenAPI) 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 partner subscription resource to communicate. In API requests, the `partnerSubscription` object informs the Merchant about updates made by the Reseller to the subscription, and vice versa.
Within MarketONE, the partner subscription resource is identified by `partnerSubscriptionId` and represented by a `partnerSubscription` object.
**Partner Subscription: A State Machine**
MarketONE simplifies the management of bundled [Platform-managed](g_platformManagedFlow) subscriptions by tracking the flow status in a state machine. A state machine is a model that defines an entity's various states and the transitions that occur based on different actions or events.
Merchants and Resellers (Service Providers) are asynchronously notified of changes to the partner subscription's service status by [events](OTTcallbacks_r) sent to their [webhooks](OTTcallbacks_r) (or notification endpoints, which only apply to Resellers). Events include the `partnerSubscription` object which shows the partner subscription's latest `serviceStatus`.
For example:
```
{
"partnerSubscriptionId": "string",
"serviceStatus": "UNPROVISIONED",
// ...other fields
}
```
**Partner Subscription Service Statuses**
A partner subscription can have the following service statuses throughout its lifecycle:
* **UNPROVISIONED**: The initial `serviceStatus` for every partner subscription is `UNPROVISIONED`. At the Reseller's (Service Provider's) instruction, MarketONE created the partner subscription and informed the Merchant. MarketONE hasn’t received a response from the Merchant yet. Merchants won't see this status, but Resellers may view it until the Merchant responds.
* **Next steps**: The Merchant needs to acknowledge the subscription, signaling they are ready to process it. Until then, the subscription remains `UNPROVISIONED`.
* **INACTIVE**: The Merchant acknowledged the creation of the partner subscription and responded to MarketONE. The Merchant or MarketONE generated and sent the redemption code. However, the customer has not yet activated the service.
* **Next steps**: The customer needs to activate their subscription. This typically involves following a link to the Merchant's site and providing an activation code.
* **ACTIVE**: The customer has successfully activated the service. The customer now has access to the service as the Reseller originally intended. Both the Reseller and Merchant can now consider the subscription provisioned and active.
* **PAUSED**: The customer’s entitlement to the service has been paused. This can occur for various reasons, such as billing issues or the customer choosing to pause their subscription (if the Merchant supports this feature). When the service is paused, the customer should not be able to access subscription features. When the reason for pausing the partner subscription is resolved, the partner subscription will go back to its previous status.
* **Next steps**: Service can typically be resumed once the payment is retried and successfully processed or upon the user's request for reactivation.
* **CANCELLED**: The partner subscription and the customer’s entitlement to the service have been canceled. The customer's access to the Merchant's service has ended. Cancellation may result from a customer payment failure, the subscription reaching the end of its cycle without renewal, or a Reseller canceling the subscription, on behalf of the customer, through an API request to MarketONE. When the partner subscription has been canceled, it can't be renewed. A new subscription would need to be created. For more information on cancellation scenarios, see [Canceled Subscriptions and Reason Codes](subscriptionCancellationReasonCodes_r).
**Partner Subscription Service Status Transitions**
| Current Service Status | Service Status the Partner Subscription Can Transition To |
| - | - |
| `UNPROVISIONED` | `INACTIVE` |
| `INACTIVE` | `ACTIVE` or `PAUSED` or `CANCELLED` |
| `ACTIVE` | `PAUSED` or `CANCELLED` |
| `PAUSED` | `ACTIVE` or `INACTIVE` depending on where the pause came from |
| `CANCELLED` | N/A |
**Common Customer Scenarios**
* **User activation delayed**: If a customer doesn’t activate their service promptly, the partner subscription stays `INACTIVE`. The Reseller (Service Provider) or Merchant can send a reminder or offer support to complete the activation.
* **Paused state due to billing**: When billing fails, an `ACTIVE` partner subscription might move to `PAUSED`. Customers need to resolve the billing issue to regain access.
* **Cancellation and what it means**: Cancellation might occur because it was initiated by the customer or by system issues such as prolonged billing failures. Once `CANCELLED`, the partner subscription cannot be restored. A new one must be created to regain access.
**Partner Subscription In-Progress Service Statuses**
The partner subscription can also have in-progress statuses like `UPDATE-IN-PROGRESS`. These in-progress statuses indicate an action needs to be taken by one party. These statuses often occur quickly and may not always be visible to Merchants and Resellers.
## Product
The product is an entity that is associated with the Merchant organization. It defines the product that is available for the Reseller (Service Provider) to monetize in a [Platform-managed flow](g_platformManagedFlow) (for example: the Spotify Individual Plan, and the Spotify Family Plan).
## Settlement
The settlement defines the settlement model (for example: revenue share or flat fee), and the Merchant share (revenue share only) or amount (flat fee only).
## Transaction
The transaction relates to the payment request that can be initiated in a [Merchant-managed flow](g_partnerManagedFlow), either by the Merchant in the case of statement billing, or by the back-end billing system of the Reseller (Service Provider) at the end of every billing cycle.
**Parent topic:**[MarketONE API Guide for Merchants Introduction](partnerAPIIntroduction)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.