openapi: 3.0.3
info:
  title: Ordergroove REST Customers Items 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: Items
  description: Line items within orders and subscriptions.
paths:
  /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.
components:
  parameters:
    PublicId:
      name: public_id
      in: path
      required: true
      schema:
        type: string
      description: The public identifier of the resource.
  schemas:
    ItemList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        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
  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).