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

{
  "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:

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:

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:

{
  "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:

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:

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

Key features

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

Integration model

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

Admin endpoints

Require SubscriptionAdmin role:

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

{
  "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

{
  "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

Portal self-service

Features:

• Manual subscription processing
• Administrator-only access
• Development debugging support
• Enhanced control

Processing limits:

Related reading

• Using extended properties in custom eCommerce apps
• Configuring user and application data access
• Ad-hoc products