NAV Navbar
shell
  • Getting started
  • Account
  • Forms
  • Sequences
  • Tags
  • Subscribers
  • Webhooks
  • Custom fields
  • Purchases
  • Getting started

    Overview

    Calls for ConvertKit API v3 are relative to the url https://api.convertkit.com/v3/

    API v3 is in active development. Currently it allows you to:

    Planning your integration

    Sweet! You're building an integration with ConvertKit. We're thrilled that you want to add-on to our platform. But before you dive in and start slinging code, let's talk about the best way to integrate with ConvertKit.

    How you setup your integration depends on what type of provider you are. Let's run through a few examples:

    If you aren't sure how best to structure your integration, just reach out to our team, we'll be happy to help you design it.

    API Basics

    API Key

    All API calls require the api_key parameter. You can find your API Key in the ConvertKit Account page.

    API Secret

    Some API calls require the api_secret parameter. All calls that require api_key also work with api_secret, there's no need to use both. This key grants access to sensitive data and actions on your subscribers, so you should treat it as your password, and do not use it in any client-side code (usually that means JavaScript).

    Responses

    When an API call goes well the API will return a 200 or 201 HTTP response, along with a JSON response body.

    If there's some error the API will return an HTTP response in the 400 or 500 range, and a response body indicating what the error was, for example:

    { "error": "Authorization Failed", "message": "API Key not present" } with a 401 error.

    Bad data

    When you create or update a field, you may receive an HTTP 422 if any fields contain bad data or required fields are missing.

    Rate limiting

    If your request rate exceeds our limits, you will receive an HTTP status of 429 with the message "Too Many Requests".

    Internal server errors

    If the server is overloaded or you encounter a bug, you will get a 500 error. Try again after a short period, and if you continue to encounter an error, please raise the issue with support.

    Account

    Show the current account

    Example Request

    curl https://api.convertkit.com/v3/account?api_secret=<your_secret_api_key>
    

    Example response

    {
        "name":"Acme Corp.",
        "primary_email_address":"you@example.com"
    }
    

    Endpoint

    GET /v3/account

    Required parameters

    Forms

    List forms

    Example Request

    
    curl https://api.convertkit.com/v3/forms?api_key=<your_public_api_key>
    

    Example Response

    
    {
      "forms": [
        {
          "id": 1,
          "name": "A Form",
          "created_at": "2016-02-28T08:07:00Z",
          "type": "embed",
          "url": "https://app.convertkit.com/landing_pages/1",
          "embed_js": "http://api.convertkit.dev/v3/forms/1.js?api_key=<your_public_api_key>",
          "embed_url": "http://api.convertkit.dev/v3/forms/1.html?api_key=<your_public_api_key>",
          "title": "Join the newsletter",
          "description": "Form description text.",
          "sign_up_button_text": "Subscribe",
          "success_message": "Success! Now check your email to confirm your subscription."
        },
        {
          "id": 2,
          "name": "A Landing Page",
          "created_at": "2016-02-28T08:07:00Z",
          "type": "hosted",
          "url": "https://app.convertkit.com/r4ndom_url/TWWDNTHT",
          "embed_js": "http://api.convertkit.dev/v3/forms/2.js?api_key=<your_public_api_key>",
          "embed_url": "http://api.convertkit.dev/v3/forms/2.html?api_key=<your_public_api_key>",
          "title": "Join the newsletter",
          "description": "<p>Landing page description text.</p>",
          "sign_up_button_text": "Subscribe",
          "success_message": "Success! Now check your email to confirm your subscription."
        }
      ]
    }
    

    Get a list of all the forms for your account.

    Endpoint

    GET /v3/forms

    Required parameters

    Add subscriber to a form

    Example Request

    
    curl -X POST https://api.convertkit.com/v3/forms/<form_id>/subscribe\
         -H "Content-Type: application/json; charset=utf-8"\
         -d
    

    Example Response

    
    {
      "subscription": {
        "id": 1,
        "state": "inactive",
        "created_at": "2016-02-28T08:07:00Z",
        "source": null,
        "referrer": null,
        "subscribable_id": 1,
        "subscribable_type": "form",
        "subscriber": {
          "id": 1,
          "first_name": "Jon",
          "email_address": "jonsnow@example.com",
          "state": "active",
          "created_at": "2016-02-28T08:07:00Z",
          "fields": {
            "last_name": "Snow"
          }
        }
      }
    }
    

    Subscribe an email address to one of your forms.

    Endpoint

    POST /v3/forms/#{form_id}/subscribe

    Required parameters

    Optional parameters

    List subscriptions to a form

    Example Request

    
    curl https://api.convertkit.com/v3/forms/<form_id>/subscriptions?api_secret=<your_secret_api_key>
    

    Example response

    {
      "total_subscriptions": 2,
      "page": 1,
      "total_pages": 1,
      "subscriptions": [
        {
          "id": 1,
          "state": "active",
          "created_at": "2016-02-28T08:07:00Z",
          "source": null,
          "referrer": null,
          "subscribable_id": 1,
          "subscribable_type": "form",
          "subscriber": {
            "id": 1,
            "first_name": "Jon",
            "email_address": "jonsnow@example.com",
            "state": "active",
            "created_at": "2016-02-28T08:07:00Z",
            "fields": {
              "last_name": "Snow"
            }
          },
        },
        {
          "id": 2,
          "state": "active",
          "created_at": "2016-02-27T08:07:00Z",
          "source": null,
          "referrer": null,
          "subscribable_id": 1,
          "subscribable_type": "form",
          "subscriber": {
            "id": 2,
            "first_name": "Arya",
            "email_address": "arya@example.com",
            "state": "active",
            "created_at": "2016-02-27T08:07:00Z",
            "fields": {
              "last_name": "Stark"
            }
          },
        }
      ]
    }
    

    List subscriptions to a form including subscriber data.

    Endpoint

    GET /v3/forms/#{form_id}/subscriptions

    Required parameters

    Optional parameters

    Sequences

    NOTE: Sequences were formerly referred to as Courses API v3 retains the previous naming conventions, but will accept requests to sequences as the endpoint as well.

    List sequences

    Example request

    
    curl https://api.convertkit.com/v3/sequences?api_key=<your_public_api_key>
    
    

    Example response

    {
      "courses": [
        {
          "id": 1,
          "name": "My First Sequence",
          "created_at": "2016-02-28T08:07:00Z"
        },
        {
          "id": 2,
          "name": "My Second Sequence",
          "created_at": "2016-02-28T08:07:00Z"
        }
      ]
    }
    

    Returns a list of sequences for the account.

    Endpoint

    GET /v3/courses

    Required parameters

    Add subscriber to a sequence

    Example request

    curl -X POST https://api.convertkit.com/v3/courses/<course_id>/subscribe\
         -H "Content-Type: application/json; charset=utf-8"\
         -d
    

    Example response

    {
      "subscription": {
        "id": 2,
        "state": "inactive",
        "created_at": "2016-02-28T08:07:00Z",
        "source": null,
        "referrer": null,
        "subscribable_id": 1,
        "subscribable_type": "course",
        "subscriber": {
          "id": 1,
          "first_name": "Jon",
          "email_address": "jonsnow@example.com",
          "state": "active",
          "created_at": "2016-02-28T08:07:00Z",
          "fields": {
            "last_name": "Snow"
          }
        }
      }
    }
    

    Subscribe an email address to one of your sequences.

    Endpoint

    POST /v3/courses/#{course_id}/subscribe

    Required parameters

    Optional parameters

    List subscriptions to a sequence

    Example request

    curl https://api.convertkit.com/v3/sequences/<sequence_id>/subscriptions?api_secret=<your_secret_api_key>
    

    Example response

    {
      "total_subscriptions": 2,
      "page": 1,
      "total_pages": 1,
      "subscriptions": [
        {
          "id": 1,
          "state": "active",
          "created_at": "2016-02-28T08:07:00Z",
          "source": null,
          "referrer": null,
          "subscribable_id": 1,
          "subscribable_type": "course",
          "subscriber": {
            "id": 1,
            "first_name": "Jon",
            "email_address": "jonsnow@example.com",
            "state": "active",
            "created_at": "2016-02-28T08:07:00Z",
            "fields": {
              "last_name": "Snow"
            }
          },
        },
        {
          "id": 2,
          "state": "active",
          "created_at": "2016-02-27T08:07:00Z",
          "source": null,
          "referrer": null,
          "subscribable_id": 1,
          "subscribable_type": "course",
          "subscriber": {
            "id": 2,
            "first_name": "Arya",
            "email_address": "arya@example.com",
            "state": "active",
            "created_at": "2016-02-27T08:07:00Z",
            "fields": {
              "last_name": "Stark"
            }
          },
        }
      ]
    }
    

    List subscriptions to a sequence including subscriber data.

    Endpoint

    GET /v3/sequences/#{sequence_id}/subscriptions

    Required parameters

    Optional parameters

    Tags

    List tags

    Example request

    curl https://api.convertkit.com/v3/tags?api_key=<your_public_api_key>
    

    Example response

    {
      "tags": [
        {
          "id": 1,
          "name": "House Stark",
          "created_at": "2016-02-28T08:07:00Z"
        },
        {
          "id": 2,
          "name": "House Lannister",
          "created_at": "2016-02-28T08:07:00Z"
        }
      ]
    }
    

    Returns a list of tags for the account.

    Endpoint

    GET /v3/tags

    Required parameters

    Create a tag

    Example request

    
    Single tag
    
    curl -X POST https://api.convertkit.com/v3/tags
         -H 'Content-Type: application/json'\
         -d '{ "api_key": "<your_public_api_key>",\
               "tag": {\
                 "name": "Example Tag"\
               } }'
    
    Multiple tags
    
    curl -X POST https://api.convertkit.com/v3/tags
         -H 'Content-Type: application/json'\
         -d '{ "api_key": "<your_public_api_key>",\
               "tag": [{\
                 "name": "Example Tag"\
               }, {\
                 "name": "Example Tag 2"\
               }] }'
    
    

    Example response

    {
      "account_id": 1,
      "created_at": "2017-04-12T11:10:32Z"
      "deleted_at": null,
      "id": 1,
      "name": "Example Tag",
      "state": "available",
      "updated_at": "2017-04-12T11:10:32Z"
    }
    
    A request to create multiple tags will receive a JSON array with the same type of objects:
    
    [{
      "account_id": 1,
      "created_at": "2017-04-12T11:10:32Z"
      "deleted_at": null,
      "id": 1,
      "name": "Example Tag",
      "state": "available",
      "updated_at": "2017-04-12T11:10:32Z"
    },
    {
      "account_id": 1,
      "created_at": "2017-04-12T11:11:566Z"
      "deleted_at": null,
      "id": 1,
      "name": "Example Tag 2",
      "state": "available",
      "updated_at": "2017-04-12T11:11:566Z"
    }]
    

    Endpoint

    POST /v3/tags

    Required parameters

    Tag a subscriber

    Example request

    curl -X POST https://api.convertkit.com/v3/tags/<tag_id>/subscribe\
         -H "Content-Type: application/json; charset=utf-8"\
         -d
    

    Example response

    {
      "subscription": {
        "id": 3,
        "state": "inactive",
        "created_at": "2016-02-28T08:07:00Z",
        "source": null,
        "referrer": null,
        "subscribable_id": 1,
        "subscribable_type": "tag",
        "subscriber": {
          "id": 1,
          "first_name": "Jon",
          "email_address": "jonsnow@example.com",
          "state": "active",
          "created_at": "2016-02-28T08:07:00Z",
          "fields": {
            "last_name": "Snow"
          }
        }
      }
    }
    

    Tags are handled as subscriptions. Subscribe an email address to a tag to have that tag applied to the subscriber with that email address.

    Endpoint

    POST /v3/tags/#{tag_id}/subscribe

    Required parameters

    Optional parameters

    Remove tag from a subscriber

    Example request

    curl -X DELETE https://api.convertkit.com/v3/subscribers/<subscriber_id>/tags/<tag_id>?api_secret=<your_secret_api_key>
    

    Example response

    {
      "id": 1,
      "name": "House Stark",
      "created_at": "2016-02-28T08:07:00Z"
    }
    

    Endpoint

    DELETE /v3/subscribers/#{subscriber_id}/tags/#{tag_id}

    Required parameters

    List subscriptions to a tag

    Example request

    
    curl https://api.convertkit.com/v3/tags/<tag_id>/subscriptions?api_secret=<your_secret_api_key>
    
    

    Example response

    {
      "total_subscriptions": 2,
      "page": 1,
      "total_pages": 1,
      "subscriptions": [
        {
          "id": 1,
          "state": "active",
          "created_at": "2016-02-28T08:07:00Z",
          "source": null,
          "referrer": null,
          "subscribable_id": 1,
          "subscribable_type": "tag",
          "subscriber": {
            "id": 1,
            "first_name": "Jon",
            "email_address": "jonsnow@example.com",
            "state": "active",
            "created_at": "2016-02-28T08:07:00Z",
            "fields": {
              "last_name": "Snow"
            }
          },
        },
        {
          "id": 2,
          "state": "active",
          "created_at": "2016-02-27T08:07:00Z",
          "source": null,
          "referrer": null,
          "subscribable_id": 1,
          "subscribable_type": "tag",
          "subscriber": {
            "id": 2,
            "first_name": "Arya",
            "email_address": "arya@example.com",
            "state": "active",
            "created_at": "2016-02-27T08:07:00Z",
            "fields": {
              "last_name": "Stark"
            }
          },
        }
      ]
    }
    

    List subscriptions to a tag including subscriber data.

    Endpoint

    GET /v3/tags/#{tag_id}/subscriptions

    Required parameters

    Optional parameters

    Subscribers

    List subscribers

    Example request

    curl https://api.convertkit.com/v3/subscribers?api_secret=<your_secret_api_key>&from=2016-02-01&to=2015-02-28
    

    Example response

    {
      "total_subscribers": 3,
      "page": 1,
      "total_pages": 1,
      "subscribers": [
        {
          "id": 1,
          "first_name": "Jon",
          "email_address": "jonsnow@example.com",
          "state": "active",
          "created_at": "2016-02-28T08:07:00Z",
          "fields": {
            "last_name": "Snow"
          }
        },
        {
          "id": 2,
          "first_name": "Arya",
          "email_address": "aryastark@example.com",
          "state": "active",
          "created_at": "2016-02-28T08:07:00Z",
          "fields": {
            "last_name": "Stark"
          }
        }
      ]
    }
    

    Returns a list of your subscribers. For unsubscribes only, use the cancelled_at value for sort_fieldparam (currently the only supported extra sort field). Search subscribers by email address by providing the email_address param.

    Endpoint

    GET /v3/subscribers

    Required parameters

    Optional parameters

    View a single subscriber

    Example request

    curl https://api.convertkit.com/v3/subscribers/1?api_secret=<your_secret_api_key>
    

    Example response

    {
      "subscriber": {
        "id": 1,
        "first_name": "Jon",
        "email_address": "jonsnow@example.com",
        "state": "active",
        "created_at": "2016-02-28T08:07:00Z",
        "fields": {
          "last_name": "Snow"
        }
      }
    }
    

    Returns data for a single subscriber

    Endpoint

    GET /v3/subscribers/#{subscriber_id}

    Required parameters

    Update subscriber

    Example request

    curl -X PUT https://api.convertkit.com/v3/subscribers/1\
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>",\
               "first_name": "Jon",\
               "email_address": "jonsnow@example.com",\
               "fields": {\
                 "last_name": "Snow"\
               } }'
    

    Example response

    {
      "subscriber": {
        "id": 1,
        "first_name": "Jon",
        "email_address": "jonsnow@example.com",
        "state": "active",
        "created_at": "2016-02-28T08:07:00Z",
        "fields": {
          "last_name": "Snow"
        }
      }
    }
    

    Updates the information for a single subscriber.

    Endpoint

    PUT /v3/subscribers/#{subscriber_id}

    Required parameters

    Optional parameters

    Unsubscribe subscriber

    Example request

    curl -x PUT https://api.convertkit.com/v3/unsubscribe
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>",\
               "email": "jonsnow@example.com" }'
    

    Example response

    {
      "subscriber": {
        "id": 1,
        "first_name": "Jon",
        "email_address": "jonsnow@example.com",
        "state": "active",
        "created_at": "2016-02-28T08:07:00Z",
        "fields": {
          "last_name": "Snow"
        }
      }
    }
    

    Unsubscribe an email address from all your forms and sequences.

    Endpoint

    PUT /v3/unsubscribe

    Required parameters

    List tags for a subscriber

    Example request

    curl -X GET https://api.convertkit.com/v3/subscribers/<tag_id>/tags\
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>" }'
    

    Example response

    {
      "tags": [
        {
          "id": 1,
          "name": "Email Newsletter",
          "created_at": "2016-06-09T17:54:22Z"
        }
      ]
    }
    

    Lists all the tags for a subscriber.

    Endpoint

    GET /v3/subscribers/#{subscriber_id}/tags

    Required parameters

    Webhooks

    Example JSON Payload

    {
      "subscriber": {
        "id": 1,
        "first_name": "John",
        "email_address": "John@example.com",
        "state": "active",
        "created_at": "2018-02-15T19:40:24.913Z",
        "fields": {
          "My Custom Field": "Value"
        }
      }
    }
    
    

    Webhooks are automations that will receive subscriber data when a subscriber event is triggered, such as when a subscriber completes a sequence.

    When a webhook is triggered, a POST request will be made to your url with a JSON payload.

    Create a webhook

    Example request: Create a webhook automation to receive subscriber data at http://example.com/incoming when a subscriber is activated.

    
    curl -X POST https://api.convertkit.com/v3/automations/hooks
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>",\
               "target_url": "http://example.com/incoming",\
               "event": { "name": "subscriber.subscriber_activate" } }'
    
    

    Example response

    {
      "rule": {
        "id": 1,
        "account_id": 2,
        "event": {
          "name": "subscriber_activate"
        }
      }
    }
    
    

    Example request: Create a webhook automation to receive subscriber data at http://example.com/incoming when a sequence is completed.

    
    curl -X POST https://api.convertkit.com/v3/automations/hooks
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>",\
               "target_url": "http://example.com/incoming",\
               "event": { "name": "subscriber.course_complete", "sequence_id": 18" } }'
    
    

    Example response

    {
      "rule": {
        "id": 43,
        "account_id":2,
        "event": {
          "name": "course_complete",
          "sequence_id": 18
        },
        "target_url":"http://example.com/"
      }
    }
    

    Create a webhook that will be called when a subscriber event occurs.

    Endpoint

    POST /v3/automations/hooks

    Required parameters

    These are the available event types:

    Destroy webhook

    Example request: Delete webhook automation rule with ID #456.

    curl -X DELETE https://api.convertkit.com/v3/automations/hooks/456
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>" }'
    

    Example response

    {
      "success": true
    }
    

    Deletes a webhook.

    Endpoint

    DELETE /v3/automations/hooks/#{rule_id}

    Required parameters

    Custom fields

    A custom field allows you to collect subscriber information beyond the standard fields of first name and email address. An example would be a custom field called last name so you can get the full names of your subscribers. You create a custom field, and then you're able to use that in your forms or with the API (see the subscribers endpoint for adding custom field values to a subscriber.)

    Note that you must create a custom field before you can use it with the subscribe methods on the forms, sequences, and tags endpoints.

    List fields

    Example request

    curl -X GET 'https://api.convertkit.com/v3/custom_fields?api_key=<your_public_api_key>'
    

    Example response

    {
      "custom_fields":
      [
        {
          "id": 1,
          "name": "ck_field_1_last_name",
          "key": "last_name",
          "label": "Last Name"
        },
        {
          "id": 2,
          "name": "ck_field_2_occupation",
          "key": "occupation",
          "label": "Occupation"
        },
      ]
    }
    

    List all of your account's custom fields.

    Endpoint

    GET /v3/custom_fields

    Required parameters

    Create field

    Example request

    
    Single label
    
    curl -X POST https://api.convertkit.com/v3/custom_fields\
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>",
               "label": "Occupation" }'
    
    Multiple labels
    
    curl -X POST https://api.convertkit.com/v3/custom_fields\
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>",
               "label": ["Occupation", "Location"] }'
    

    Response: Single custom field

    {
      "id": 1,
      "name": "ck_field_1_occupation",
      "key": "occupation",
      "label": "Occupation"
    }
    

    Response: Multiple custom fields

    [{
      "id": 1,
      "name": "ck_field_1_occupation",
      "key": "occupation",
      "label": "Occupation"
    },
    {
      "id": 2,
      "name": "ck_field_2_occupation",
      "key": "location",
      "label": "Location"
    }]
    

    Create a custom field for your account. The label field must be unique to your account. Whitespace will be removed from the beginning and the end of your label.

    Additionally, a key field and a name field will be generated for you. The key is an ASCII-only, lowercased, underscored representation of your label. This key must be unique to your account. Keys are used in personalization tags in sequences and broadcasts. Names are unique identifiers for use in the HTML of custom forms. They are made up of a combination of ID and the key of the custom field prefixed with "ck_field".

    Endpoint

    POST /v3/custom_fields

    Required parameters

    Update field

    Example request

    curl -X PUT https://api.convertkit.com/v3/custom_fields/1\
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>",
               "label": "Profession" }'
    

    Example response

    No content will be returned.
    

    Updates a custom field label (see create field above for more information on labels). Note that the key and the name do not change even when the label is updated.

    Endpoint

    PUT /v3/custom_fields/#{your custom field ID}

    Required parameters

    Destroy field

    Example request

    curl -X DELETE https://api.convertkit.com/v3/custom_fields/1\
         -H 'Content-Type: application/json'\
         -d '{ "api_secret": "<your_secret_api_key>" }'
    

    Example response

    No content will be returned.
    

    Destroys a custom field. Note that this will remove all data in this field from your subscribers.

    Endpoint

    DELETE /v3/custom_fields/#{your custom field ID}

    Required parameters

    Purchases

    List Purchases

    Example request: Retrieve all purchases for an account

    curl -X GET https://api.convertkit.com/v3/purchases \
          -H 'Content-Type: application/json' \
          -d '{ "api_secret": "<your_secret_api_key>", "page": 1 }'
    

    Success response: HTTP/1.1 200 OK

    {
        "total_purchases": 2,
        "page": 1,
        "total_pages": 1,
        "purchases": [
            {
                "id": 3,
                "transaction_id": "123-abcd-456-efgh",
                "status": "paid",
                "email_address": "x@example.com",
                "currency": "JPY",
                "transaction_time": "2018-03-20 12:38",
                "subtotal": 20.0,
                "shipping": 2.0,
                "discount": 3.0,
                "tax": 2.0,
                "total": 21.0,
                "products": [
                    {
                      "unit_price": 5.0,
                      "quantity": 2,
                      "sku": "7890-ijkl",
                      "name": "Floppy Disk (512k)"
                    },
                    {
                      "unit_price": 10.0,
                      "quantity": 1,
                      "sku":"mnop-1234",
                      "name":"Telephone Cord (data)"
                    }
                ]
            },
            {
                "id": 4,
                "transaction_id": "123-abcd-457-efgh",
                "status": "paid",
                "email_address": "x@example.com",
                "currency": "USD",
                "transaction_time": "2018-03-20 13:38",
                "subtotal": 20.0,
                "shipping": 2.0,
                "discount": 3.0,
                "tax": 2.0,
                "total": 21.0,
                "products": [
                    {
                        "unit_price": 5.0,
                        "quantity": 2,
                        "sku": "7890-ijkl",
                        "name": "Floppy Disk (512k)"
                    },
                    {
                        "unit_price": 10.0,
                        "quantity": 1,
                        "sku": "mnop-1234",
                        "name": "Telephone Cord (data)"
                    }
                ]
            }
        ]
    }
    

    Failure response. For example, when api_secret is not provided: HTTP/1.1 401 Unauthorized

    {
        "error":"Authorization Failed",
        "message":"You do not have sufficient permissions to access this resource"
    }
    

    Show all purchases for an account

    Endpoint

    GET /v3/purchases

    Required parameters

    Optional parameters

    Retrieve a specific Purchase

    Example request: get purchases with ID 8

    curl -X GET https://api.convertkit.com/v3/purchases/8 \
         -H 'Content-Type: application/json' \
         -d '{ "api_secret": "<your_secret_api_key>" }
    

    Success response: HTTP/1.1 200 OK

    {
        "id": 8,
        "transaction_id": "123-abcd-456-efgh",
        "status": "paid",
        "email_address": "crashoverride@hackers.com",
        "currency": "JPY",
        "transaction_time": "2018-03-20 14:31",
        "subtotal": 20.0,
        "shipping": 2.0,
        "discount": 3.0,
        "tax": 2.0,
        "total": 21.0,
        "products": [
            {
                "unit_price": 5.0,
                "quantity": 2,
                "sku": "7890-ijkl",
                "name": "Floppy Disk (512k)"
            },
            {
                "unit_price": 10.0,
                "quantity": 1,
                "sku": "mnop-1234",
                "name": "Telephone Cord (data)"
            }
        ]
    }
    

    Failure response. For example, when api_secret is not provided: HTTP/1.1 401 Unauthorized

    {
        "error":"Authorization Failed",
        "message":"You do not have sufficient permissions to access this resource"
    }
    

    Show specific purchase by ID

    Endpoint

    GET /v3/purchases/#{id}

    Required parameters

    Create a Purchase

    Example request: get all purchases

    curl -X POST https://api.convertkit.com/v3/purchases \
         -H 'Content-Type: application/json' \
         -d '{ "api_secret": "<your_secret_api_key>",
               "purchase": {
                    "transaction_id": "123-abcd-456-efgh",
                    "email_address": "crashoverride@hackers.com",
                    "currency": "jpy",
                    "transaction_time": "2018-03-20 14:31:10",
                    "subtotal": 20.00,
                    "tax": 2.00,
                    "shipping": 2.00,
                    "discount": 3.00,
                    "total": 21.00,
                    "status": "paid",
                    "products": [{
                        "pid": 9999,
                        "lid": 7777,
                        "name": "Floppy Disk (512k)",
                        "sku": "7890-ijkl",
                        "unit_price": 5.00,
                        "quantity": 2
                    }, {
                        "pid": 5555,
                        "lid": 7778,
                        "name": "Telephone Cord (data)",
                        "sku": "mnop-1234",
                        "unit_price": 10.00,
                        "quantity": 1
                    }]
               }
         }'
    

    Success response: HTTP/1.1 201 Created

    {
        "id": 8,
        "transaction_id": "123-abcd-456-efgh",
        "status": "paid",
        "email_address": "crashoverride@hackers.com",
        "currency": "JPY",
        "transaction_time": "2018-03-20 14:31",
        "subtotal": 20.0,
        "discount": 3.0,
        "tax": 2.0,
        "shipping": 2.00,
        "total": 21.0,
        "products": [
            {
                "unit_price": 5.0,
                "quantity": 2,
                "sku": "7890-ijkl",
                "name": "Floppy Disk (512k)"
            },
            {
                "unit_price": 10.0,
                "quantity": 1,
                "sku": "mnop-1234",
                "name": "Telephone Cord (data)"
            }
        ]
    }
    

    Failure response: HTTP/1.1 400 Bad Request

    {
        "error": "Your request is missing parameters",
        "message": "transaction_id can't be blank, Sku can't be blank for product: Floppy Disk (512k)"
    }
    

    Endpoint

    POST /v3/purchases

    Required parameters

    Optional parameters

    Update a specific Purchase

    Example request: update purchases with ID 8

    curl -X PUT https://api.convertkit.com/v3/purchases/8 \
         -H 'Content-Type: application/json' \
         -d '{ "api_secret": "<your_secret_api_key>",
               "purchase": {
                    "status": "refund"
               }
            }'
    
    

    Success response: HTTP/1.1 200 OK

    {
        "id": 8,
        "transaction_id": "123-abcd-456-efgh",
        "status": "refund",
        "email_address": "crashoverride@hackers.com",
        "currency": "JPY",
        "transaction_time": "2018-03-20 14:31",
        "subtotal": 20.0,
        "discount": 3.0,
        "tax": 2.0,
        "shipping": 2.00,
        "total": 21.0,
        "products": [
            {
                "unit_price": 5.0,
                "quantity": 2,
                "sku": "7890-ijkl",
                "name": "Floppy Disk (512k)"
            },
            {
                "unit_price": 10.0,
                "quantity": 1,
                "sku": "mnop-1234",
                "name": "Telephone Cord (data)"
            }
        ]
    }
    

    Failure response: HTTP/1.1 400 Bad Request

    {
        "error": "Your request is missing parameters",
        "message": "transaction_id can't be blank, Sku can't be blank for product: Floppy Disk (512k)"
    }
    

    Note: status is only changeable field

    Endpoint

    PUT /v3/purchases/#{id}

    Required parameters

    Optional parameters