---
title: Subscriptions
slug: subscriptions
abstract: Subscription functionality enables automated ordering for buyer users on set intervals
content_type: concept
audience: \[business-user, architect]
---
# Subscriptions

Subscription functionality enables automated ordering for buyer users on set intervals. This feature provides convenient, predictable delivery of goods or services while fostering customer loyalty. Implementation requires subscription integration for order submission.

## Use cases

### Consumable goods

- Customer-defined schedules
- Regular replenishment
- Flexible ordering options

### Service subscriptions

- Monthly memberships
- Digital services
- Recurring billing

### Product collections

- Standardized bundles
- Customized packages
- Regular delivery intervals

## Key features

### Scheduling

- Configurable intervals
- Adjustable frequency
- Optional end dates
- Indefinite processing

### Payment handling

- OrderCloud Payment integration
- Multiple payment methods
- Secure processing
- Automated billing

### User management

- Unlimited user subscriptions
- Seller-created subscriptions
- User visibility controls
- Role-based access

### Pricing options

- `SubscriptionPrice` on PriceBreak
- Bundle price precedence
- Sale price support
- Standard pricing fallback

Price resolution order:

1. `BundlePrice` (if defined)
2. `SubscriptionPrice`
3. `SalePrice`
4. Standard `Price`

## Subscription resource

### Model definition

```json
{
  "ID": "subscription1",
  "Interval": "Days",
  "Frequency": 1,
  "NextOrderDate": "2022-11-19+00:00",
  "LastOrderDate": "2022-10-19T20:40:06.73+00:00",
  "EndDate": null,
  "FromCompanyID": "buyerCompany",
  "FromUserID": "buyerUser",
  "ToCompanyID": "sellerCompany",
  "BillingAddressID": "billingAddress",
  "ShippingAddressID": "shippingAddress",
  "Payment": {
    "Type": "CreditCard",
    "CreditCardID": "creditcardid",
    "SpendingAccountID": null
  },
  "xp": {}
}
```

### Admin endpoints

Require SubscriptionAdmin/Reader roles:

```http
GET v1/subscriptions
GET v1/subscriptions/{subscriptionID}
POST v1/subscriptions
PUT v1/subscriptions/{subscriptionID}
PATCH v1/subscriptions/{subscriptionID}
DELETE v1/subscriptions/{subscriptionID}
```

Additional requirements:

- OrderAdmin role
- UnsubmittedOrderReader role

### User endpoints

Require MeSubscriptionAdmin/Shopper roles:

```http
GET v1/me/subscriptions
GET v1/me/subscriptions/{subscriptionID}
POST v1/me/subscriptions
PUT v1/me/subscriptions/{subscriptionID}
PATCH v1/me/subscriptions/{subscriptionID}
DELETE v1/me/subscriptions/{subscriptionID}
```

## Subscription items

### Item model

Used for line item creation during processing:

```json
{
  "ID": "shipmentItem1",
  "ProductID": "product1",
  "Quantity": 1,
  "DateAdded": "2018-08-09T17:53:35.997+00:00",
  "QuantityShipped": 0,
  "UnitPrice": 15.0,
  "PromotionDiscount": 0,
  "LineTotal": 15.0,
  "LineSubtotal": 15.0,
  "CostCenter": null,
  "DateNeeded": null,
  "ShippingAccount": null,
  "ShippingAddressID": null,
  "ShipFromAddressID": null,
  "Product": {},
  "Variant": null,
  "ShippingAddress": {},
  "ShipFromAddress": null,
  "SupplierID": null,
  "InventoryRecordID": null,
  "PriceScheduleID": null,
  "PriceOverridden": false,
  "Specs": [],
  "xp": {}
}
```

### Admin endpoints

Require SubscriptionAdmin/Reader roles:

```http
GET v1/subscriptions/{subscriptionID}/items
GET v1/subscriptions/{subscriptionID}/items/{subscriptionItemID}
POST v1/subscriptions/{subscriptionID}/items
PUT v1/subscriptions/{subscriptionID}/items/{subscriptionItemID}
PATCH v1/subscriptions/{subscriptionID}/items/{subscriptionItemID}
DELETE v1/subscriptions/{subscriptionID}/items/{subscriptionItemID}
```

### User endpoints

Require MeSubscriptionAdmin/Shopper roles:

```http
GET v1/me/subscriptions/{subscriptionID}/items
GET v1/me/subscriptions/{subscriptionID}/items/{subscriptionItemID}
POST v1/me/subscriptions/{subscriptionID}/items
PUT v1/me/subscriptions/{subscriptionID}/items/{subscriptionItemID}
PATCH v1/me/subscriptions/{subscriptionID}/items/{subscriptionItemID}
DELETE v1/me/subscriptions/{subscriptionID}/items/{subscriptionItemID}
```

## Subscription integration

### Overview

Required for subscription order processing:

- Hourly order creation
- Line item generation
- Payment processing
- Checkout handling

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/d28d27146ecd47558160eeac69eec1df.png)

### Key features

- One integration per marketplace
- Configurable notification days
- Dedicated API client
- Default context user required
- Custom checkout handling

### Integration model

```json
{
  "ApiClientID": "",
  "HashKey": "",
  "ElevatedRoles": [],
  "Active": true,
  "NotificationDays": 15,
  "Url": "",
  "xp": {}
}
```

### Admin endpoints

Require SubscriptionAdmin role:

```http
GET v1/integrations/subscription
PUT v1/integrations/subscription
PATCH v1/integrations/subscription
DELETE v1/integrations/subscription
```

### Processing logic

- Hourly subscription check
- Five-hour processing window
- Retry on failure
- Active user validation

## Integration payloads

### Request payload

```json
{
  "Environment": "Sandbox",
  "OrderCloudAccessToken": "",
  "OrderWorksheet": {},
  "UnavailableProductIDs": ["inactiveProduct"],
  "ErrorCode": ""
}
```

### Success handling

Endpoint: `{base_url}/success`

- Order creation confirmation
- Payment capture
- Tax calculation
- Shipping configuration
- Order submission

### Failure handling

Endpoint: `{base_url}/failure`

- Error processing
- Custom handling
- Error logging
- Recovery procedures

### Response format

```json
{
  "HttpStatusCode": 200,
  "UnhandledErrorBody": ""
}
```

Response processing:

- Updates NextOrderDate
- Stores in OrderWorksheet
- Validates status code
- Handles errors

## Notification system

### Reminder messages

- Hourly notification check
- Active subscription validation
- Notification date calculation
- Email delivery

## Related reading

- [Using extended properties in custom eCommerce apps](https://doc.sitecore.com/ordercloud/en/developers/platform/extended-properties.html#using-extended-properties-in-custom-ecommerce-apps)
- [Ad-hoc products](https://doc.sitecore.com/ordercloud/en/developers/platform/ad-hoc-products.html)
- [Portal self-service](https://doc.sitecore.com/ordercloud/en/developers/platform/using-the-portal.html#portal-self-service)