Olo Accounts API

openapi: 3.2.0
info:
  title: Olo Promotions Accounts API
  description: The Olo Promotions Specification defines the HTTP contract that a third-party promotions / loyalty provider implements so Olo can validate and redeem coupons and loyalty rewards, accrue loyalty points, and manage loyalty accounts during the Olo ordering flow. Olo acts as the client and calls the provider-hosted endpoints described here. Requests are authenticated with an HMAC-SHA256 signature computed over the request URL concatenated with the raw request body, encoded as URL-safe base64 without padding (or with HTTP Basic for key-based auth). This specification is published at https://developer.olo.com/docs and modeled directly from Olo's official open-source Promotions SDK (github.com/ololabs/promotions-sdk).
  version: '1.0'
  contact:
    name: Olo Developer Support
    url: https://developer.olo.com/
  license:
    name: Olo Promotions SDK License
    url: https://github.com/ololabs/promotions-sdk/blob/main/LICENSE.md
servers:
- url: https://{providerHost}
  description: Provider-hosted Promotions endpoint implementing the Olo Promotions Specification
  variables:
    providerHost:
      default: promotions.example.com
      description: The promotions provider's host that implements this specification
security:
- OloSignature: []
tags:
- name: Accounts
  description: Loyalty account creation and lookup
paths:
  /promotions/accounts:
    post:
      tags:
      - Accounts
      summary: Create Account
      description: Create a new loyalty account in the provider's system for a guest.
      operationId: createAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
      responses:
        '200':
          description: The created loyalty account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      tags:
      - Accounts
      summary: Find Accounts
      description: Find loyalty accounts matching a membership number or other guest identifier.
      operationId: findAccounts
      parameters:
      - name: membershipNumber
        in: query
        required: true
        description: The membership number used to locate the guest's loyalty account(s).
        schema:
          type: string
      responses:
        '200':
          description: The list of matching loyalty accounts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /promotions/accounts/{accountId}:
    get:
      tags:
      - Accounts
      summary: Get Account
      description: Retrieve a single loyalty account by its identifier in the provider's system.
      operationId: getAccount
      parameters:
      - name: accountId
        in: path
        required: true
        description: The loyalty account's unique identifier in the provider's system.
        schema:
          type: string
      responses:
        '200':
          description: The requested loyalty account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    PosReference:
      type: object
      description: Data used to identify a promotion or reward on the POS.
      properties:
        type:
          $ref: '#/components/schemas/PosReferenceType'
        code:
          type: string
          description: The value of the POS reference.
    AccountReward:
      type: object
      description: A reward available in a loyalty account.
      properties:
        id:
          type: string
          description: A unique identifier for the loyalty reward in the provider's system.
        name:
          type: string
          description: The name of the loyalty reward.
        description:
          type: string
          description: A description of the loyalty reward.
        quantity:
          type: integer
          description: The quantity of the reward available in the account.
        currency:
          type: string
          description: A three-letter ISO 4217 currency code. Defaults to USD when omitted.
        expiration:
          type: string
          format: date-time
          description: A UTC RFC 3339 date-time representing when the reward expires.
        reference:
          $ref: '#/components/schemas/PosReference'
        type:
          type: string
          description: Provider-defined category for the reward. Echoed back; not interpreted by Olo.
        imageUrl:
          type: string
          description: An image URL representing the reward. Not interpreted by Olo.
        customFields:
          type: string
          description: Custom provider metadata echoed back in subsequent requests.
    ErrorResponse:
      type: object
      description: Returned for error responses.
      properties:
        id:
          type: string
          description: A unique identifier for the error in the provider's system.
        details:
          type: string
          description: Additional details used to help troubleshoot the error.
        message:
          type: string
          description: An error message to be shown to the customer.
    Balance:
      type: object
      description: A loyalty account's points balance.
      properties:
        quantity:
          type: number
          description: The amount of points in the user's loyalty account.
        target:
          type: number
          description: The points required to unlock the next step in the loyalty account.
        unit:
          type: string
          default: points
          description: The unit used to describe the quantity of a loyalty account balance.
    Account:
      type: object
      description: A guest's loyalty account.
      properties:
        id:
          type: string
          description: The account's unique identifier in the provider's system.
        status:
          $ref: '#/components/schemas/AccountStatus'
        balance:
          $ref: '#/components/schemas/Balance'
        rewards:
          type: array
          items:
            $ref: '#/components/schemas/AccountReward'
    AccountStatus:
      type: string
      description: Whether the loyalty account is active or inactive.
      enum:
      - Active
      - Inactive
    PosReferenceType:
      type: string
      description: The type of a POS reference.
      enum:
      - Promo
      - Comp
    CreateAccountRequest:
      type: object
      description: Request payload to create a new loyalty account.
      properties:
        firstName:
          type: string
          description: First name for the user.
        lastName:
          type: string
          description: Last name for the user.
        phoneNumber:
          type: string
          description: Phone number for the user.
        emailAddress:
          type: string
          description: Email address for the user.
        externalIdentifier:
          type: string
          description: Unique external identifier for the user.
  responses:
    Unauthorized:
      description: The request signature was invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    OloSignature:
      type: apiKey
      in: header
      name: Authorization
      description: HMAC-SHA256 signature over the request URL concatenated with the raw request body, using the shared secret as the key, encoded as URL-safe base64 without padding. HTTP Basic authorization (base64 of the shared secret) is also supported for key-based auth.
externalDocs:
  description: Olo Promotions Specification
  url: https://developer.olo.com/docs