Go to payhip.com
API Reference
Authentication
Core Resources

API Reference

The Payhip API follows RESTful principles. It uses consistent, resource-based URLs, supports form-encoded request bodies, returns responses in JSON format, and adheres to standard HTTP methods and status codes.

Use the Payhip API to create, read, and update information on your Payhip account.

At the moment we only have support for interacting with the Coupon and License Key resources, but more will be added in future.

Authentication

You'll need an API key to authenticate your requests. Please login to your account and visit your Developer Settings page to view and manage your key.

Please do ensure you keep your API key secret, treat it like just any password. If you suspect it's been exposed then you can roll your key to prevent further access.

Coupons

A coupon lets you provide a discount to customers in the form of a percentage discount (like 20% off) or fixed amount discount (like $5 off).

You can specify the end date for a coupon, the minimum purchase amount and more.

Please note coupons for subscription priced products with a recurring amount aren't possible through the API yet.

Endpoints

The Coupon object

Attributes

  • id string
    Unique identifier for the coupon object.
  • coupon_type enum
    Specifies if the coupon will be applied for a single product, all your products or a single collection
    Possible enum values
    single
    Applies to a single product.
    multi
    Applies to all your products.
    collection
    Applies to a single collection.
  • percent_off float or null
    A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if amount_off is not passed).
  • amount_off integer or null
    A positive integer representing the amount to subtract from the cart total (required if percent_off is not passed). For example if you'd like to give $5 off then amount_off would be 500 in cents.
  • code string
    The coupon code the customer is required to enter at checkout.
  • start_date datetime string or null
    RFC 3339 datetime string of when this coupon begins to be valid. Coupons can not be redeemed before this date has been reached. null if this coupon does not require a start date.
  • end_date datetime string or null
    RFC 3339 datetime string of when this coupon expires. Coupons can no longer be redeemed after this date has been reached. null if this coupon can be redeemed forever.
  • product_key string or null
    If coupon_type is set to single then the unique product key must be specified. To find out your product key, please follow these steps.
  • collection_id string or null
    If coupon_type is set to collection then the unique collection ID must be specified. To find out collection ID you can learn more here.
  • minimum_purchase_amount integer or null
    A positive integer representing the the minumum total of the customers cart before they can redeem this coupon. For example if you'd like to set the minimum as $5 then value would be 500 in cents.
  • usage_limit integer or null
    The maximum number of times this coupon can be redeemed before it becomes invalid.
  • notes string or null
    For administrative purposes you can remind yourself why you created this coupon by adding a note - not visible to customers.
Object 
{
    "amount_off": null,
    "code": "example123",
    "collection_id": null,
    "coupon_type": "single",
    "end_date": null,
    "id": "1V6B72Lzra",
    "minimum_purchase_amount": null,
    "notes": null,
    "percent_off": 50,
    "product_key": "PtRJw",
    "start_date": null,
    "usage_limit": null
}

Create a coupon

A coupon has either a percent_off or an amount_off. If you set an amount_off, that amount will be subtracted from the carts subtotal.

Parameters

  • percent_off float
    A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if amount_off is not passed).
  • amount_off integer
    A positive integer representing the amount to subtract from the cart total (required if percent_off is not passed). For example if you'd like to give $5 off then amount_off would be 500 in cents.
  • coupon_type enum
    Specifies if the coupon will be applied for a single product, all your products or a single collection
    Possible enum values
    single
    Applies to a single product.
    multi
    Applies to all your products.
    collection
    Applies to a single collection.
  • code string
    The coupon code the customer is required to enter at checkout.
  • product_key string
    If coupon_type is set to single then the unique product key must be specified. To find out your product key, please follow these steps.

More parameters

POST /api/v2/coupons 
curl https://payhip.com/api/v2/coupons \
    -d "code=example123" \
    -d "coupon_type=single" \
    -d "product_key=PtRJw" \
    -d "percent_off=25" \
    -X POST \
    --header "payhip-api-key: YOUR_API_KEY_HERE"
Response 
{
    "data": {
        "amount_off": null,
        "code": "example123",
        "collection_id": null,
        "coupon_type": "single",
        "end_date": null,
        "id": "1V6B72Lzra",
        "minimum_purchase_amount": null,
        "notes": null,
        "percent_off": 50,
        "product_key": "PtRJw",
        "start_date": null,
        "usage_limit": null
    }
}

List all coupons

Retrieve a paginated list of all the coupons created on your account

Parameters

  • limit integer
    The limit on the number of objects to be returned with the paginated results. Limit can range between 1 and 100, and the default is 10.
  • offset integer
    To move to the next results of paginated lists you can define an offet integer. By default this would be 0.
GET /api/v2/coupons 
curl -G https://payhip.com/api/v2/coupons \
    -d "limit=10" \
    -d "offset=0" \
    --header "payhip-api-key: YOUR_API_KEY_HERE"
Response 
{
    "data": {
        "coupons": [
            {
                "amount_off": null,
                "code": "example123",
                "collection_id": null,
                "coupon_type": "single",
                "end_date": null,
                "id": "1V6B72Lzra",
                "minimum_purchase_amount": null,
                "notes": null,
                "percent_off": 50,
                "product_key": "PtRJw",
                "start_date": null,
                "usage_limit": null
            }
        ]
    }
}

Retrieve a coupon

Retrieves a coupon with the given ID.

Parameters

No parameters.
GET /api/v2/coupons/:id 
curl -G https://payhip.com/api/v2/coupons/1V6B72Lzra \
    --header "payhip-api-key: YOUR_API_KEY_HERE"
Response 
{
    "data": {
        "amount_off": null,
        "code": "example123",
        "collection_id": null,
        "coupon_type": "single",
        "end_date": null,
        "id": "1V6B72Lzra",
        "minimum_purchase_amount": null,
        "notes": null,
        "percent_off": 50,
        "product_key": "PtRJw",
        "start_date": null,
        "usage_limit": null
    }
}

License Keys

A unique license key can be generated for each of your customers. You can then verify that their purchase is legitimate by requesting their license key. The is a great for software products to ensure security.

Endpoints

The License Key object

Attributes

  • license_key string
    Unique identifier for the license key object.
  • enabled boolean
    You can specify if this license key is valid by enabling or disabling it. When a refund takes place we automatically disable the license key.
  • product_link string
    The product link (or product key) is the unique ID of the product this customer purchased. To find out your product key, please follow these steps.
  • buyer_email string
    The email address the customer used for the purchase associated with this license key.
  • uses integer
    The number of times this license key has been used.
  • date datetime string
    RFC 3339 datetime string of when this license key was created.
Object 
{
    "enabled": true,
    "product_link": "mVT0",
    "license_key": "WTKP4-66NL5-HMKQW-GFSCZ",
    "buyer_email": "contact@payhip.com",
    "uses": 0,
    "date": "2024-02-22T11:23:05+00:00"
}

Verify license key

Verify a license key with the given license key.

To find your product secret key to authenticate with this request please visit your edit product page and scroll down to the checkbox where you've enabled licenses and it will be listed there.

Learn more about license keys here.

Parameters

  • license_key string
    Unique identifier for the license key object.
GET /api/v2/license/verify 
curl -G https://payhip.com/api/v2/license/verify \
    -d "license_key=WTKP4-66NL5-HMKQW-GFSCZ" \
    --header "product-secret-key: YOUR_PRODUCT_SECRET_KEY_HERE"
Response 
{
    "data": {
        "enabled": true,
        "product_link": "mVT0",
        "license_key": "WTKP4-66NL5-HMKQW-GFSCZ",
        "buyer_email": "contact@payhip.com",
        "uses": 0,
        "date": "2025-02-22T11:23:05+00:00"
    }
}

Disable license key

You might want to disable a license key if a customer breaks your terms of service for example. We automatically disable the license key if the transaction has been refunded.

To find your product secret key to authenticate with this request please visit your edit product page and scroll down to the checkbox where you've enabled licenses and it will be listed there.

Learn more about license keys here.

Parameters

  • license_key string
    Unique identifier for the license key object.
PUT /api/v2/license/disable 
curl https://payhip.com/api/v2/license/enable \
    -d "license_key=WTKP4-66NL5-HMKQW-GFSCZ" \
    -X PUT \
    --header "product-secret-key: YOUR_PRODUCT_SECRET_KEY_HERE"
Response 
{
    "data": {
        "enabled": false,
        "product_link": "mVT0",
        "license_key": "WTKP4-66NL5-HMKQW-GFSCZ",
        "buyer_email": "contact@payhip.com",
        "uses": 1,
        "date": "2025-02-22T11:23:05+00:00"
    }
}

Enable license key

You might have previously disabled a license key for a customer (eg if they broke your terms). This endpoint can be used to re-enable a license key.

To find your product secret key to authenticate with this request please visit your edit product page and scroll down to the checkbox where you've enabled licenses and it will be listed there.

Learn more about license keys here.

Parameters

  • license_key string
    Unique identifier for the license key object.
PUT /api/v2/license/enable 
curl https://payhip.com/api/v2/license/enable \
    -d "license_key=WTKP4-66NL5-HMKQW-GFSCZ" \
    -X PUT \
    --header "product-secret-key: YOUR_PRODUCT_SECRET_KEY_HERE"
Response 
{
    "data": {
        "enabled": true,
        "product_link": "mVT0",
        "license_key": "WTKP4-66NL5-HMKQW-GFSCZ",
        "buyer_email": "contact@payhip.com",
        "uses": 1,
        "date": "2025-02-22T11:23:05+00:00"
    }
}

Increase usage for license key

You can record when a customer has used this license key by increasing the usage counter.

To find your product secret key to authenticate with this request please visit your edit product page and scroll down to the checkbox where you've enabled licenses and it will be listed there.

Learn more about license keys here.

Parameters

  • license_key string
    Unique identifier for the license key object.
PUT /api/v2/license/usage 
curl https://payhip.com/api/v2/license/usage \
    -d "license_key=WTKP4-66NL5-HMKQW-GFSCZ" \
    -X PUT \
    --header "product-secret-key: YOUR_PRODUCT_SECRET_KEY_HERE"
Response 
{
    "data": {
        "enabled": true,
        "product_link": "mVT0",
        "license_key": "WTKP4-66NL5-HMKQW-GFSCZ",
        "buyer_email": "contact@payhip.com",
        "uses": 2,
        "date": "2025-02-22T11:23:05+00:00"
    }
}

Decrease usage for license key

You can control the number of uses this license key had by the customer by decreasing the usage counter.

To find your product secret key to authenticate with this request please visit your edit product page and scroll down to the checkbox where you've enabled licenses and it will be listed there.

Learn more about license keys here.

Parameters

  • license_key string
    Unique identifier for the license key object.
PUT /api/v2/license/decrease 
curl https://payhip.com/api/v2/license/usage \
    -d "license_key=WTKP4-66NL5-HMKQW-GFSCZ" \
    -X PUT \
    --header "product-secret-key: YOUR_PRODUCT_SECRET_KEY_HERE"
Response 
{
    "data": {
        "enabled": true,
        "product_link": "mVT0",
        "license_key": "WTKP4-66NL5-HMKQW-GFSCZ",
        "buyer_email": "contact@payhip.com",
        "uses": 2,
        "date": "2025-02-22T11:23:05+00:00"
    }
}