Payhip Coupons API

openapi: 3.1.0
info:
  title: Payhip API
  description: >-
    The Payhip API provides programmatic access to a Payhip creator e-commerce
    account. It follows RESTful conventions, uses resource-based URLs, accepts
    form-encoded or JSON request bodies, and returns JSON responses wrapped in a
    "data" object. The public API currently exposes two resource families -
    Coupons and software License Keys. Coupon operations authenticate with the
    account API key (payhip-api-key header); license operations authenticate with
    a per-product secret key (product-secret-key header). Both keys are managed
    from the Developer Settings page. Order, customer, and transaction data is not
    exposed as a REST resource; it is delivered through the webhooks documented in
    the "webhooks" section (paid, refunded, subscription.created,
    subscription.deleted), whose payloads carry a signature equal to
    hash('sha256', apiKey). Not all Payhip features are available in the API;
    Payhip states more resources are planned.
  version: '2.0'
  contact:
    name: Payhip
    url: https://payhip.com
  x-modeled: >-
    Paths, methods, webhook event names, and field names are taken from Payhip's
    published API reference (payhip.com/api-reference) and webhooks help article.
    Request/response schemas expand documented fields into typed properties and
    should be reconciled against a live account response.
servers:
  - url: https://payhip.com/api/v2
    description: Payhip public API
tags:
  - name: Coupons
    description: Create, list, and retrieve discount coupons.
  - name: License Keys
    description: Verify and manage software license keys issued for Payhip products.
paths:
  /coupons:
    post:
      operationId: createCoupon
      tags:
        - Coupons
      summary: Create a coupon
      description: >-
        Creates a discount coupon for a product or collection. Provide either
        percent_off or amount_off.
      security:
        - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponInput'
      responses:
        '200':
          description: The created coupon.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: listCoupons
      tags:
        - Coupons
      summary: List coupons
      description: Lists all coupons on the account, paginated.
      security:
        - apiKeyAuth: []
      parameters:
        - name: page
          in: query
          required: false
          description: Page number for paginated results.
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: A paginated list of coupons.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Coupon'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /coupons/{id}:
    get:
      operationId: getCoupon
      tags:
        - Coupons
      summary: Retrieve a coupon
      description: Retrieves a single coupon by its identifier.
      security:
        - apiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The identifier of the coupon.
          schema:
            type: string
      responses:
        '200':
          description: The requested coupon.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /license/verify:
    get:
      operationId: verifyLicense
      tags:
        - License Keys
      summary: Verify a license key
      description: >-
        Validates a license key and returns its status plus buyer, product, and
        usage details.
      security:
        - productSecretAuth: []
      parameters:
        - name: license_key
          in: query
          required: true
          description: The license key to verify.
          schema:
            type: string
      responses:
        '200':
          description: The license key and its details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /license/enable:
    put:
      operationId: enableLicense
      tags:
        - License Keys
      summary: Enable a license key
      description: Reactivates a previously disabled license key.
      security:
        - productSecretAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseKeyRef'
      responses:
        '200':
          description: The updated license key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /license/disable:
    put:
      operationId: disableLicense
      tags:
        - License Keys
      summary: Disable a license key
      description: Deactivates a license key so it no longer verifies as valid.
      security:
        - productSecretAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseKeyRef'
      responses:
        '200':
          description: The updated license key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /license/usage:
    put:
      operationId: increaseLicenseUsage
      tags:
        - License Keys
      summary: Increment license usage
      description: Increments the usage counter for a license key by one.
      security:
        - productSecretAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseKeyRef'
      responses:
        '200':
          description: The updated license key with its new usage count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /license/decrease:
    put:
      operationId: decreaseLicenseUsage
      tags:
        - License Keys
      summary: Decrement license usage
      description: Decrements the usage counter for a license key by one.
      security:
        - productSecretAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseKeyRef'
      responses:
        '200':
          description: The updated license key with its new usage count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
webhooks:
  paid:
    post:
      operationId: onPaid
      summary: Customer charged
      description: >-
        Sent when a customer is charged for a purchase. Monetary amounts are in
        cents. Verify authenticity by comparing the signature field with
        hash('sha256', apiKey).
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionEvent'
      responses:
        '200':
          description: Acknowledged. Payhip retries hourly for up to three hours on non-200.
  refunded:
    post:
      operationId: onRefunded
      summary: Payment refunded
      description: Sent when a payment is refunded. Amounts are in cents.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionEvent'
      responses:
        '200':
          description: Acknowledged.
  subscriptionCreated:
    post:
      operationId: onSubscriptionCreated
      summary: Subscription created
      description: Sent when a new membership/subscription begins.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionEvent'
      responses:
        '200':
          description: Acknowledged.
  subscriptionDeleted:
    post:
      operationId: onSubscriptionDeleted
      summary: Subscription deleted
      description: Sent when a membership/subscription is cancelled.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionEvent'
      responses:
        '200':
          description: Acknowledged.
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: payhip-api-key
      description: Account API key from the Developer Settings page. Used for coupon operations.
    productSecretAuth:
      type: apiKey
      in: header
      name: product-secret-key
      description: Per-product secret key from the Developer Settings page. Used for license key operations.
  responses:
    Unauthorized:
      description: Missing or invalid API key / product secret key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CouponEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Coupon'
    LicenseEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/LicenseKey'
    CouponInput:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: The coupon code customers enter at checkout.
        coupon_type:
          type: string
          description: Scope of the coupon.
          enum:
            - single
            - multi
            - collection
        percent_off:
          type: number
          description: Percentage discount. Provide this or amount_off.
        amount_off:
          type: integer
          description: Fixed discount in cents. Provide this or percent_off.
        product_key:
          type: string
          description: The product the coupon applies to (for single/multi coupons).
        collection_id:
          type: string
          description: The collection the coupon applies to (for collection coupons).
        minimum_purchase_amount:
          type: integer
          description: Minimum cart total in cents required for the coupon to apply.
        usage_limit:
          type: integer
          description: Maximum number of times the coupon can be redeemed.
        start_date:
          type: string
          format: date
          description: Date the coupon becomes active.
        end_date:
          type: string
          format: date
          description: Date the coupon expires.
        notes:
          type: string
          description: Internal notes about the coupon.
    Coupon:
      allOf:
        - $ref: '#/components/schemas/CouponInput'
        - type: object
          properties:
            id:
              type: string
              description: Unique identifier for the coupon.
            usage_count:
              type: integer
              description: Number of times the coupon has been redeemed.
    LicenseKeyRef:
      type: object
      required:
        - license_key
      properties:
        license_key:
          type: string
          description: The license key to act on.
    LicenseKey:
      type: object
      properties:
        license_key:
          type: string
        enabled:
          type: boolean
          description: Whether the key currently verifies as valid.
        product_link:
          type: string
          description: URL slug/link of the product the key belongs to.
        product_name:
          type: string
        variant_id:
          type: string
        variant_name:
          type: string
        buyer_email:
          type: string
          format: email
        uses:
          type: integer
          description: Current usage count for the key.
        date:
          type: string
          format: date-time
          description: When the key was issued.
    TransactionEvent:
      type: object
      description: >-
        Payload for paid and refunded webhooks. Amounts are in cents. Delivered
        as an outbound HTTP POST, not fetchable via REST.
      properties:
        type:
          type: string
          enum:
            - paid
            - refunded
        id:
          type: string
          description: Transaction identifier.
        email:
          type: string
          format: email
          description: Customer email.
        price:
          type: integer
          description: Amount in cents.
        currency:
          type: string
        items:
          type: array
          description: Items purchased.
          items:
            type: object
            additionalProperties: true
        payment_type:
          type: string
          description: Payment processor / method used.
        signature:
          type: string
          description: Equals hash('sha256', apiKey). Use to verify authenticity.
        date:
          type: string
          format: date-time
    SubscriptionEvent:
      type: object
      description: Payload for subscription.created and subscription.deleted webhooks.
      properties:
        type:
          type: string
          enum:
            - subscription.created
            - subscription.deleted
        id:
          type: string
          description: Subscription identifier.
        email:
          type: string
          format: email
        plan_name:
          type: string
        product_name:
          type: string
        signature:
          type: string
          description: Equals hash('sha256', apiKey).
        date:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string