Olo Accruals API

openapi: 3.2.0
info:
  title: Olo Promotions Accruals 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: Accruals
  description: Loyalty point accrual and void
paths:
  /promotions/accruals:
    post:
      tags:
      - Accruals
      summary: Accrue Points
      description: Accrue loyalty points for a placed order against a guest's loyalty account.
      operationId: accruePoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccruePointsRequest'
      responses:
        '200':
          description: A transaction confirming the accrual.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEnvelope'
        '400':
          $ref: '#/components/responses/BadRequestWithCode'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /promotions/accruals/{accrualId}:
    delete:
      tags:
      - Accruals
      summary: Void Accrual
      description: Void a previously recorded loyalty point accrual for an order.
      operationId: voidAccrual
      parameters:
      - name: accrualId
        in: path
        required: true
        description: The identifier of the accrual being voided.
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoidAccrualRequest'
      responses:
        '200':
          description: A transaction confirming the voided accrual.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEnvelope'
        '400':
          $ref: '#/components/responses/BadRequestWithCode'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Handoff:
      type: string
      description: The handoff method for the order.
      enum:
      - Pickup
      - Curbside
      - Delivery
      - Dispatch
      - Drivethru
      - Dinein
    VoidAccrualRequest:
      type: object
      description: Request payload to void a previously recorded loyalty point accrual.
      properties:
        orderId:
          type: string
          description: The ID of the order being voided.
        accountId:
          type: string
          description: The loyalty account's unique identifier in the provider's system.
        brand:
          type: string
          description: A unique ID representing the restaurant brand in Olo's system.
        storeNumber:
          type: string
          description: The ID of the store as provided by the restaurant.
        restaurant:
          type: string
          description: A unique ID representing the vendor restaurant in Olo's system.
    OloItem:
      type: object
      description: An Olo-represented basket item.
      properties:
        product:
          type: string
          description: The Olo product ID.
        label:
          type: string
          description: The name of the product in Olo's system.
        cost:
          type: number
          description: The per-unit cost of the product in Olo's system.
    Source:
      type: string
      description: The source of the order.
      enum:
      - Web
      - MobileWeb
      - iOS
      - Android
      - Kiosk
      - Other
    Modifier:
      type: object
      description: A POS modifier applied to a product, supporting nested modifiers.
      properties:
        id:
          type: string
          description: The POS modifier ID.
        quantity:
          type: number
          description: The quantity of the modifier applied to the product.
        product:
          type: string
          description: The POS product ID the modifier is applied to.
        categories:
          type: array
          description: The POS category IDs for the modifier.
          items:
            type: string
        label:
          type: string
          description: The name of the modifier on the POS.
        cost:
          type: number
          description: The per-unit cost of the modifier on the POS.
        modifiers:
          type: array
          description: The modifiers applied to the modifier.
          items:
            $ref: '#/components/schemas/Modifier'
    Address:
      type: object
      description: The destination address of the order.
      properties:
        street:
          type: string
          description: The street address.
        city:
          type: string
          description: The name of the city.
        code:
          type: string
          description: The zip code.
        country:
          type: string
          description: A three-letter ISO 3166-1 country code.
    Payment:
      type: object
      description: A payment applied to the order.
      properties:
        tender:
          $ref: '#/components/schemas/Tender'
        issuer:
          $ref: '#/components/schemas/Issuer'
        suffix:
          type: string
          description: The credit card suffix. Only populated when tender is Credit.
        amount:
          type: number
          description: The payment amount for this payment method.
    Basket:
      type: object
      description: The basket contents for an order.
      properties:
        id:
          type: string
          description: The ID of the basket; the unique order identifier until an order ID is generated.
        rewards:
          type: array
          description: Any loyalty rewards applied to the basket.
          items:
            $ref: '#/components/schemas/BasketReward'
        coupons:
          type: array
          description: Any coupons applied to the basket.
          items:
            $ref: '#/components/schemas/Coupon'
        entries:
          type: array
          description: The Olo representations of the basket items.
          items:
            $ref: '#/components/schemas/OloEntry'
        posEntries:
          type: array
          description: The POS representations of the basket items.
          items:
            $ref: '#/components/schemas/PosEntry'
    Coupon:
      type: object
      description: A coupon applied to a basket.
      properties:
        id:
          type: string
          description: The coupon's code.
        provider:
          type: string
          description: The name of the coupon's provider.
        level:
          $ref: '#/components/schemas/DiscountLevel'
        product:
          type: string
          description: The Olo product ID the coupon is applied to. Only populated for item-level coupons.
        discount:
          type: number
          description: The discount amount for the coupon. Only populated once the basket is validated.
    PosEntry:
      type: object
      description: A POS-represented basket item entry.
      properties:
        quantity:
          type: number
          description: The quantity of the item in the basket.
        posItem:
          $ref: '#/components/schemas/PosItem'
    ErrorCodeResponse:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
      - type: object
        properties:
          code:
            $ref: '#/components/schemas/ErrorCode'
    AccruePointsRequest:
      type: object
      description: Request payload to accrue loyalty points for an order.
      properties:
        orderId:
          type: string
          description: The ID of the order, only populated once the order has been placed.
        accountId:
          type: string
          description: The loyalty account's unique identifier in the provider's system.
        source:
          $ref: '#/components/schemas/Source'
        handoff:
          $ref: '#/components/schemas/Handoff'
        currency:
          type: string
          description: A three-letter ISO 4217 currency code. Defaults to USD when omitted.
        placed:
          type: string
          format: date-time
          description: A UTC RFC 3339 date-time representing when the order was created.
        wanted:
          type: string
          format: date-time
          description: A UTC RFC 3339 date-time representing when the guest wants to receive their food.
        storeNumber:
          type: string
          description: The ID of the store as provided by the restaurant.
        restaurant:
          type: string
          description: A unique ID representing the vendor restaurant in Olo's system.
        brand:
          type: string
          description: A unique ID representing the restaurant brand in Olo's system.
        subtotal:
          type: number
          description: The cost of the food before applying any tax, tip, fees or discounts.
        tax:
          type: number
          description: The amount of tax applied to the order.
        tip:
          type: number
          description: The amount the customer tipped on the order.
        delivery:
          type: number
          description: The delivery fee for the order.
        customFees:
          type: number
          description: The sum of any custom fees applied to the order.
        discount:
          type: number
          description: The sum of any discounts applied to the order.
        total:
          type: number
          description: The final total for the order after any tax, tip, fees and discounts.
        address:
          $ref: '#/components/schemas/Address'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        basket:
          $ref: '#/components/schemas/Basket'
      required:
      - accountId
      - subtotal
      - total
    OloEntry:
      type: object
      description: An Olo-represented basket item entry.
      properties:
        quantity:
          type: number
          description: The quantity of the item in the basket.
        item:
          $ref: '#/components/schemas/OloItem'
    PosItem:
      type: object
      description: A POS-represented basket item.
      properties:
        product:
          type: string
          description: The POS product ID.
        categories:
          type: array
          description: The POS category IDs for the product.
          items:
            type: string
        modifiers:
          type: array
          description: The modifiers applied to the product.
          items:
            $ref: '#/components/schemas/Modifier'
        label:
          type: string
          description: The name of the product on the POS.
        cost:
          type: number
          description: The per-unit cost of the product on the POS.
    ErrorCode:
      type: string
      description: A machine-readable code identifying the issue with the request.
      enum:
      - EXPIRED_PROMOTION
      - INVALID_PROMOTION
      - MISSING_ITEM
      - INVALID_TOTAL
      - INVALID_HANDOFF
      - INVALID_ACCOUNT
      - OTHER
    BasketReward:
      type: object
      description: A loyalty reward applied to a basket.
      properties:
        id:
          type: string
          description: The ID of the reward in the loyalty provider's system.
        provider:
          type: string
          description: The name of the reward's loyalty provider.
        level:
          $ref: '#/components/schemas/DiscountLevel'
        product:
          type: string
          description: The Olo product ID the reward is applied to. Only populated for item-level rewards.
        discount:
          type: number
          description: The discount amount for the reward. Only populated once the basket is validated.
        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.
    Issuer:
      type: string
      description: The credit card issuer. Only populated when tender is Credit.
      enum:
      - Amex
      - Diners
      - Discover
      - JCB
      - MasterCard
      - PayPal
      - Visa
    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.
    DiscountLevel:
      type: string
      description: The level at which a discount is applied.
      enum:
      - Item
      - Basket
    Tender:
      type: string
      description: A payment tender type.
      enum:
      - Cash
      - Check
      - Credit
      - Debit
      - Prepaid
      - Transfer
      - Value
      - Other
    Transaction:
      type: object
      description: The result of a Promotions operation.
      properties:
        id:
          type: string
          description: A unique identifier for the transaction in the provider's system.
    TransactionEnvelope:
      type: object
      description: An envelope wrapping a transaction result.
      properties:
        transaction:
          $ref: '#/components/schemas/Transaction'
  responses:
    Unauthorized:
      description: The request signature was invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequestWithCode:
      description: The request could not be processed; a machine-readable error code is included.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorCodeResponse'
  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