Cavuno Coupons API

openapi: 3.2.0
info:
  title: Cavuno v1 REST Coupons API
  version: 1.0.0
  description: 'The Cavuno API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ## Base URL


    Production: `https://api.cavuno.com/v1`


    All API requests must be made over HTTPS. Calls made over plain HTTP will fail. ## Authentication


    The Cavuno API uses API keys to authenticate requests. You can view and manage your API keys in the Cavuno dashboard, under Settings → Developer → API keys. Cavuno API keys have the prefix `cavuno_live_`. Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via Bearer auth. Provide your API key as the bearer token in the `Authorization` header:


    ```bash

    curl https://api.cavuno.com/v1/jobs \

    -H "Authorization: Bearer YOUR_SECRET_API_KEY"

    ```


    API requests without authentication will fail. ## Rate limits


    The Cavuno API has rate limits in place to ensure stability and reliability. By default, API keys are limited to 100 requests per minute. If you exceed your limit, requests return an HTTP 429 response with a `Retry-After` header indicating when you can try again. If you have a use case that needs a higher limit, contact support. ## Idempotency


    The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a job fails due to a network connection error, you can safely retry the request with the same idempotency key, and we''ll guarantee that only one job is created. To perform an idempotent request, provide an additional `Idempotency-Key` header on any `POST`, `PATCH`, or `DELETE` request:


    ```bash

    curl https://api.cavuno.com/v1/jobs \

    -X POST \

    -H "Authorization: Bearer cavuno_live_..." \

    -H "Idempotency-Key: $(uuidgen)" \

    -H "Content-Type: application/json" \

    -d ''{ "title": "Senior Engineer" }''

    ```


    ## Errors


    Cavuno uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the `5xx` range indicate an error with Cavuno''s servers (these are rare). Error responses include a JSON body with details:


    ```json

    {

    "error": {

    "code": "validation_bad_request",

    "message": "Field ''title'' is required.",

    "requestId": "req_..."

    }

    }

    ```


    Some errors carry an additional `details` field with structured context, such as per-field validation issues. ### Plan upgrade hints


    When an Operator API request is refused because of the board''s Cavuno plan, the error also carries an `upgrade` object. It names the capability that blocked the request, the cheapest self-serve plan that unlocks it (when that can be told), and the hosted billing endpoints that start the upgrade:


    ```json

    {

    "error": {

    "code": "settings_plan_required_for_branding_removal",

    "message": "Removing Cavuno branding requires a plan that includes branding removal.",

    "requestId": "req_...",

    "upgrade": {

    "capability": "canRemoveBranding",

    "requiredPlan": "basic",

    "checkout": { "method": "POST", "path": "/v1/billing/checkout" },

    "changePlan": { "method": "POST", "path": "/v1/billing/upgrade" }

    }

    }

    }

    ```


    Call `GET /v1/billing/subscription` first. With no active subscription, use `checkout`; with one, use `changePlan`. Send `{ "planKey": "" }` and give the returned `url` to a person: both endpoints return a hosted page where a person confirms the purchase. Nothing is charged until they do. Each `path` is relative to the API origin (`https://api.cavuno.com`), like `Location` headers and list `url` fields, so do not join it to a base URL that already ends in `/v1`.'
  contact:
    name: Cavuno
    url: https://cavuno.com
servers:
- url: https://api.cavuno.com/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Coupons
  description: Coupons and promotion codes on your connected Stripe account.
paths:
  /coupons:
    get:
      summary: List coupons
      description: List the Board's coupons. Provider configuration and identifiers remain private.
      responses:
        '200':
          description: Coupons.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  url:
                    type: string
                    example: /v1/coupons
                  hasMore:
                    type: boolean
                  nextCursor:
                    type:
                    - string
                    - 'null'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Coupon'
                required:
                - object
                - url
                - hasMore
                - nextCursor
                - data
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Coupons
      operationId: listCoupons
    post:
      summary: Create a coupon
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCouponBody'
      responses:
        '201':
          description: Created coupon.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Coupons
      operationId: createCoupon
  /coupons/{id}:
    get:
      summary: Get a coupon
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The coupon id.
        required: true
        description: The coupon id.
        name: id
        in: path
      responses:
        '200':
          description: The coupon.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Coupons
      operationId: getCoupon
    patch:
      summary: Rename a coupon
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The coupon id.
        required: true
        description: The coupon id.
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameCouponBody'
      responses:
        '200':
          description: Updated coupon.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Coupons
      operationId: updateCoupon
    delete:
      summary: Delete a coupon
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The coupon id.
        required: true
        description: The coupon id.
        name: id
        in: path
      responses:
        '204':
          description: Deleted.
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Coupons
      operationId: deleteCoupon
  /coupons/{id}/promotion-codes:
    get:
      summary: List promotion codes
      description: Lists the promotion codes of one coupon, newest first, 100 per page, including inactive and expired codes, with how often each was redeemed.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The coupon id.
        required: true
        description: The coupon id.
        name: id
        in: path
      - schema:
          type: string
          description: Opaque cursor (a promotion code id) to fetch the next page.
        required: false
        description: Opaque cursor (a promotion code id) to fetch the next page.
        name: cursor
        in: query
      responses:
        '200':
          description: Promotion codes of the coupon.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  url:
                    type: string
                    example: /v1/coupons/{id}/promotion-codes
                  hasMore:
                    type: boolean
                  nextCursor:
                    type:
                    - string
                    - 'null'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PromotionCode'
                required:
                - object
                - url
                - hasMore
                - nextCursor
                - data
        '404':
          description: No coupon with this id on the Board.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Coupons
      operationId: listPromotionCodes
    post:
      summary: Create a promotion code
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The coupon id.
        required: true
        description: The coupon id.
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePromotionCodeBody'
      responses:
        '201':
          description: Created promotion code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromotionCode'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Coupons
      operationId: createCouponPromotionCode
  /coupons/promotion-codes/{id}/archive:
    post:
      summary: Archive a promotion code
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The promotion code id.
        required: true
        description: The promotion code id.
        name: id
        in: path
      responses:
        '200':
          description: Archived promotion code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromotionCode'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Coupons
      operationId: archivePromotionCode
components:
  schemas:
    CreateCouponBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 40
        percentOff:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 100
        amountOff:
          type:
          - number
          - 'null'
          description: Fixed discount in the currency major unit (e.g. 10 for $10, 1000 for ¥1000). Required with `currency` when there is no percentOff.
          exclusiveMinimum: 0
        currency:
          type:
          - string
          - 'null'
          minLength: 1
        duration:
          type: string
          enum:
          - once
          - forever
          - repeating
        durationInMonths:
          type: integer
          exclusiveMinimum: 0
        maxRedemptions:
          type: integer
          exclusiveMinimum: 0
        redeemBy:
          type: integer
          description: Unix ms deadline after which the coupon cannot be redeemed.
        appliesToPlanIds:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - name
      - duration
      additionalProperties: false
    PromotionCode:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - promotion_code
        code:
          type: string
        couponId:
          type: string
        active:
          type: boolean
        created:
          type: string
        maxRedemptions:
          type:
          - integer
          - 'null'
          description: How many times the code can be redeemed in total, or null for no limit.
        timesRedeemed:
          type: integer
          minimum: 0
          description: How many times the code has been redeemed.
        expiresAt:
          type:
          - string
          - 'null'
          description: ISO-8601 time the code stops working, or null.
      required:
      - id
      - object
      - code
      - couponId
      - active
      - created
      - maxRedemptions
      - timesRedeemed
      - expiresAt
    CreatePromotionCodeBody:
      type: object
      properties:
        code:
          type: string
          minLength: 1
        maxRedemptions:
          type: integer
          exclusiveMinimum: 0
        expiresAt:
          type: string
          format: date-time
          description: ISO-8601 expiry for the promotion code.
        firstTimeTransaction:
          type: boolean
        minimumAmount:
          type: number
          exclusiveMinimum: 0
        minimumAmountCurrency:
          type: string
          minLength: 1
      required:
      - code
      additionalProperties: false
    Coupon:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - coupon
        name:
          type:
          - string
          - 'null'
        percentOff:
          type:
          - number
          - 'null'
        amountOff:
          type:
          - number
          - 'null'
        currency:
          type:
          - string
          - 'null'
        duration:
          type: string
        durationInMonths:
          type:
          - number
          - 'null'
        valid:
          type: boolean
        appliesTo:
          type:
          - array
          - 'null'
          items:
            type: string
        timesRedeemed:
          type: number
        created:
          type: string
      required:
      - id
      - object
      - name
      - percentOff
      - amountOff
      - currency
      - duration
      - durationInMonths
      - valid
      - appliesTo
      - timesRedeemed
      - created
    RenameCouponBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 40
      required:
      - name
      additionalProperties: false
    PlanUpgradeHint:
      type: object
      properties:
        capability:
          type: string
          enum:
          - activeJobsLimit
          - teamSeatLimit
          - canBePublic
          - canRemoveBranding
          - apiAccess
          description: The plan capability that blocked the request, named as in `GET /v1/billing/subscription` `capabilities`.
        requiredPlan:
          type: string
          enum:
          - starter
          - basic
          - grow
          - advanced
          - scale
          description: The cheapest self-serve plan that unlocks the action. Pass it as `planKey`. Omitted when it cannot be told without more information; read `GET /v1/billing/subscription` and pick a higher plan.
        checkout:
          type: object
          properties:
            method:
              type: string
              enum:
              - POST
            path:
              type: string
              enum:
              - /v1/billing/checkout
          required:
          - method
          - path
          description: Starts a hosted checkout when the board has no active subscription (for example during a trial).
        changePlan:
          type: object
          properties:
            method:
              type: string
              enum:
              - POST
            path:
              type: string
              enum:
              - /v1/billing/upgrade
          required:
          - method
          - path
          description: Starts a hosted plan change when the board already has an active subscription.
      required:
      - capability
      - checkout
      - changePlan
      description: 'Present only on Operator API errors caused by the board''s Cavuno plan. Read `GET /v1/billing/subscription` to choose between `checkout` and `changePlan`, call it with `{ "planKey": requiredPlan }`, and give the returned `url` to a person to confirm. Each `path` is relative to the API origin, not to a `/v1` base URL. Both endpoints need `billing.manage`. Board API errors never include it.'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code, such as `validation_bad_request` or `jobs_not_found`.
            message:
              type: string
              description: Human-readable explanation.
            requestId:
              type: string
              description: Unique id for this request. Include it when contacting support.
            details:
              description: Structured context for some errors, such as per-field validation issues.
            upgrade:
              $ref: '#/components/schemas/PlanUpgradeHint'
          required:
          - code
          - message
          - requestId
      required:
      - error
      description: The error envelope returned by every non-2xx response.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cavuno_live_<keyId>_<secret>
      description: Use your secret API key to authenticate. Pass it as a Bearer token in the `Authorization` header. You can view and manage your API keys in the Cavuno dashboard.
externalDocs:
  description: Cavuno API reference
  url: https://cavuno.com/docs/api