Manage the central customer profile that ties together subscriptions, orders, addresses, and payment methods - list, retrieve, create, and update customers, and set their contact details. Customer-scoped listing across multiple customers requires the Bulk Operations permission on the Application API scope.
openapi: 3.0.3
info:
title: Ordergroove REST API
description: >-
The Ordergroove REST API operates an enterprise subscription and
relationship-commerce program on top of a merchant's eCommerce store. It is
organized around a four-object data model - Customer, Subscription, Item, and
Order - plus supporting resources for Products, Offers and Incentives,
Payments, Addresses, and Entitlements. Two authentication scopes exist: an
Application API scope for server-to-server calls using an x-api-key header
(one of ten keys per store), and a Storefront API scope using an
HMAC-SHA256-signed request scoped to a single customer. All traffic is HTTPS
only. This document models the publicly documented REST surface at
restapi.ordergroove.com; endpoint paths are drawn from the public API
reference. Ordergroove is an enterprise platform sold through sales, so an
account and API keys are required to call the API, but the reference is
publicly readable.
version: '1.0'
contact:
name: Ordergroove Developer
url: https://developer.ordergroove.com
servers:
- url: https://restapi.ordergroove.com
description: Production
- url: https://staging.restapi.ordergroove.com
description: Staging
security:
- apiKeyAuth: []
tags:
- name: Subscriptions
description: Recurring subscription agreements.
- name: Customers
description: Central customer profiles.
- name: Orders
description: Recurring orders generated by subscriptions.
- name: Items
description: Line items within orders and subscriptions.
- name: Products
description: Product catalog and product groups.
- name: Offers
description: Offers, incentives, discounts, and entitlements.
- name: Payments
description: Customer payment methods.
- name: Addresses
description: Customer shipping addresses.
- name: Webhooks
description: Outbound event notifications.
paths:
/subscriptions/:
get:
operationId: listSubscriptions
tags:
- Subscriptions
summary: List subscriptions
description: >-
Lists subscriptions, filterable by customer, product, shipping address,
live status, and created/updated date ranges. Listing across more than
one customer requires the Bulk Operations permission.
parameters:
- name: customer
in: query
schema:
type: string
description: Filter by customer ID (Application scope only).
- name: product
in: query
schema:
type: string
- name: live
in: query
schema:
type: boolean
- name: created_start
in: query
schema:
type: string
format: date
- name: created_end
in: query
schema:
type: string
format: date
responses:
'200':
description: A paginated list of subscriptions.
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionList'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/subscriptions/{public_id}/:
get:
operationId: retrieveSubscription
tags:
- Subscriptions
summary: Retrieve a subscription
parameters:
- $ref: '#/components/parameters/PublicId'
responses:
'200':
description: A subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'401':
$ref: '#/components/responses/Unauthorized'
put:
operationId: updateSubscription
tags:
- Subscriptions
summary: Update a subscription
parameters:
- $ref: '#/components/parameters/PublicId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
responses:
'200':
description: The updated subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
/subscriptions/{public_id}/cancel/:
post:
operationId: cancelSubscription
tags:
- Subscriptions
summary: Cancel a subscription
parameters:
- $ref: '#/components/parameters/PublicId'
responses:
'200':
description: The cancelled subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
/subscriptions/{public_id}/reactivate/:
post:
operationId: reactivateSubscription
tags:
- Subscriptions
summary: Reactivate a subscription
parameters:
- $ref: '#/components/parameters/PublicId'
responses:
'200':
description: The reactivated subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
/subscriptions/{public_id}/change_frequency/:
post:
operationId: changeSubscriptionFrequency
tags:
- Subscriptions
summary: Change subscription frequency
parameters:
- $ref: '#/components/parameters/PublicId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
every:
type: integer
every_period:
type: string
enum: [day, week, month, year]
responses:
'200':
description: The updated subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
/customers/:
get:
operationId: listCustomers
tags:
- Customers
summary: List customers
responses:
'200':
description: A paginated list of customers.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCustomer
tags:
- Customers
summary: Create a customer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
responses:
'201':
description: The created customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
/customers/{public_id}/:
get:
operationId: retrieveCustomer
tags:
- Customers
summary: Retrieve a customer
parameters:
- $ref: '#/components/parameters/PublicId'
responses:
'200':
description: A customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
put:
operationId: updateCustomer
tags:
- Customers
summary: Update a customer
parameters:
- $ref: '#/components/parameters/PublicId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
responses:
'200':
description: The updated customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
/orders/:
get:
operationId: listOrders
tags:
- Orders
summary: List orders
parameters:
- name: customer
in: query
schema:
type: string
- name: status
in: query
schema:
type: string
responses:
'200':
description: A paginated list of orders.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderList'
'401':
$ref: '#/components/responses/Unauthorized'
/orders/{public_id}/:
get:
operationId: retrieveOrder
tags:
- Orders
summary: Retrieve an order
parameters:
- $ref: '#/components/parameters/PublicId'
responses:
'200':
description: An order.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
/orders/{public_id}/cancel/:
post:
operationId: cancelOrder
tags:
- Orders
summary: Cancel an order
parameters:
- $ref: '#/components/parameters/PublicId'
responses:
'200':
description: The cancelled order.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
/orders/{public_id}/send_now/:
post:
operationId: sendOrderNow
tags:
- Orders
summary: Send an order now
parameters:
- $ref: '#/components/parameters/PublicId'
responses:
'200':
description: The updated order.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
/items/:
get:
operationId: listItems
tags:
- Items
summary: List items
parameters:
- name: subscription
in: query
schema:
type: string
- name: order
in: query
schema:
type: string
responses:
'200':
description: A paginated list of items.
content:
application/json:
schema:
$ref: '#/components/schemas/ItemList'
post:
operationId: createItem
tags:
- Items
summary: Create an item
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
responses:
'201':
description: The created item.
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
/items/{public_id}/:
get:
operationId: retrieveItem
tags:
- Items
summary: Retrieve an item
parameters:
- $ref: '#/components/parameters/PublicId'
responses:
'200':
description: An item.
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
delete:
operationId: deleteItem
tags:
- Items
summary: Delete an item
parameters:
- $ref: '#/components/parameters/PublicId'
responses:
'204':
description: The item was deleted.
/products/:
get:
operationId: listProducts
tags:
- Products
summary: List products
responses:
'200':
description: A paginated list of products.
content:
application/json:
schema:
$ref: '#/components/schemas/ProductList'
/products/{id}/:
get:
operationId: retrieveProduct
tags:
- Products
summary: Retrieve a product
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: A product.
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
put:
operationId: updateProduct
tags:
- Products
summary: Update a product
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
responses:
'200':
description: The updated product.
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
/offer_profiles/:
get:
operationId: listOfferProfiles
tags:
- Offers
summary: List offer profiles
description: >-
Lists the offer profiles (incentive logic) that can be applied to
recurring purchases.
responses:
'200':
description: A list of offer profiles.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/OfferProfile'
/otd/:
get:
operationId: listOneTimeDiscounts
tags:
- Offers
summary: List one-time discounts
responses:
'200':
description: A list of one-time discounts.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/OneTimeDiscount'
post:
operationId: createOneTimeDiscount
tags:
- Offers
summary: Create a one-time discount
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OneTimeDiscount'
responses:
'201':
description: The created one-time discount.
content:
application/json:
schema:
$ref: '#/components/schemas/OneTimeDiscount'
/entitlements/:
get:
operationId: listEntitlements
tags:
- Offers
summary: List entitlements
parameters:
- name: customer
in: query
schema:
type: string
responses:
'200':
description: A list of entitlements.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Entitlement'
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Application API scope. Send one of the ten store API keys in the
x-api-key header for server-to-server requests. Storefront requests use
an HMAC-SHA256 signature scoped to a single customer instead (out of band
of this scheme).
parameters:
PublicId:
name: public_id
in: path
required: true
schema:
type: string
description: The public identifier of the resource.
responses:
Unauthorized:
description: Authentication failed or the API key is missing or invalid.
TooManyRequests:
description: >-
Rate limit exceeded (more than 6000 requests per IP per minute). Safe to
retry.
schemas:
Subscription:
type: object
properties:
id:
type: string
public_id:
type: string
customer_id:
type: string
product_id:
type: string
quantity:
type: integer
payment_id:
type: string
shipping_address_id:
type: string
offer_id:
type: string
every:
type: integer
every_period:
type: string
enum: [day, week, month, year]
live:
type: boolean
SubscriptionList:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Subscription'
next:
type: string
nullable: true
previous:
type: string
nullable: true
Customer:
type: object
properties:
id:
type: string
public_id:
type: string
merchant_id:
type: string
merchant_user_id:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
CustomerList:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Customer'
next:
type: string
nullable: true
previous:
type: string
nullable: true
Order:
type: object
properties:
id:
type: string
public_id:
type: string
customer_id:
type: string
place:
type: string
format: date-time
status:
type: string
description: 'Order status: unsent, pending, success, rejected, etc.'
sub_total:
type: string
shipping_total:
type: string
total:
type: string
order_merchant_id:
type: string
payment_id:
type: string
shipping_address_id:
type: string
OrderList:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Order'
next:
type: string
nullable: true
previous:
type: string
nullable: true
Item:
type: object
properties:
id:
type: string
public_id:
type: string
order_id:
type: string
subscription_id:
type: string
nullable: true
product_id:
type: string
quantity:
type: integer
price:
type: string
total_price:
type: string
offer_id:
type: string
one_time:
type: boolean
ItemList:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Item'
next:
type: string
nullable: true
previous:
type: string
nullable: true
Product:
type: object
properties:
id:
type: string
price:
type: string
external_product_id:
type: string
autoship_enabled:
type: boolean
ProductList:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Product'
next:
type: string
nullable: true
previous:
type: string
nullable: true
OfferProfile:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
OneTimeDiscount:
type: object
properties:
id:
type: string
customer_id:
type: string
amount:
type: string
type:
type: string
Entitlement:
type: object
properties:
id:
type: string
customer_id:
type: string
status:
type: string