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