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.
  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:
    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.
    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'
    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.
    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.
    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.
    TransactionEnvelope:
      type: object
      description: An envelope wrapping a transaction result.
      properties:
        transaction:
          $ref: '#/components/schemas/Transaction'
    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
    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.
    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'
    Issuer:
      type: string
      description: The credit card issuer. Only populated when tender is Credit.
      enum:
      - Amex
      - Diners
      - Discover
      - JCB
      - MasterCard
      - PayPal
      - Visa
    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'
    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'
    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.
    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
    Source:
      type: string
      description: The source of the order.
      enum:
      - Web
      - MobileWeb
      - iOS
      - Android
      - Kiosk
      - Other
    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.
    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.
    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.
    Handoff:
      type: string
      description: The handoff method for the order.
      enum:
      - Pickup
      - Curbside
      - Delivery
      - Dispatch
      - Drivethru
      - Dinein
    ErrorCodeResponse:
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
      - type: object
        properties:
          code:
            $ref: '#/components/schemas/ErrorCode'
  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