Receive server-to-endpoint HTTP callbacks for account events - paid (customer charged), refunded, subscription.created, and subscription.deleted - carrying transaction, customer, item, and subscription details. Payloads include a signature that verifies authenticity as hash('sha256', apiKey). This is how order, customer, and transaction data reaches external applications; there is no pollable REST resource for them.
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