openapi: 3.0.3
info:
  title: Ordergroove REST Customers Subscriptions 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.
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'
components:
  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
  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.
  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).