{
  "aid": "tilled.com:main-1.0",
  "name": "Tilled API",
  "type": "Index",
  "description": "The Tilled API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer).\nOur API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\nYou can use the Tilled API in test mode, which does not affect your live data or interact with the banking networks.\nThe API key you use to authenticate the request determines whether the request is live mode or test mode.\nBefore your account is activated you will only be able to interact with test mode.\n\nAuthentication uses a standard web token schema.\n\n**Notice**: The Tilled API treats HTTP status `401` to mean `Unauthenticated`\nand not the HTTP standard name of `Unauthorized`.\nRequests made for materials the requester does not have permission to access, the API will respond with `403: Forbidden`.\n\n# Authentication\n\nThe tilled API uses API keys to authenticate requests. You can view and manage your API keys in the\nTilled Dashboard.\n\nTest mode secret keys have the prefix sk*test* and live mode secret keys have the prefix sk*live*.\nAlternatively, you can use restricted API keys for granular permissions.\n\nYour API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys\nin publicly accessible areas such as GitHub, client-side code, and so forth.\n\nAuthentication to the API is performed via custom HTTP Header `tilled-api-key`. Provide your API key as the value.\n\nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests\nwithout authentication will also fail.\n\n<!-- ReDoc-Inject: <security-definitions> -->\n\n# Errors\n\nTilled uses conventional HTTP response codes to indicate the success or failure of an API request.\nIn general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error\nthat failed given the information provided (e.g., a required parameter was omitted, a charge failed,\netc.). Codes in the `5xx` range indicate an error with Tilled's servers (these are rare).\n\nSome `4xx` errors that could be handled programmatically (e.g., a card is declined)\ninclude an error code that briefly explains the error reported.\n\n# Request IDs\n\nEach API request has an associated request identifier. You can find this value in the response headers, under `request-id`. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.\n\n# Metadata\n\nUpdatable Tilled objects—including [Account](https://api.tilled.com), [Customer](https://api.tilled.com), [PaymentIntent](https://api.tilled.com), [Refund](https://api.tilled.com), and [Subscription](https://api.tilled.com)—have a `metadata` parameter. You can use this parameter to attach key-value data to these Tilled objects.\n\nYou can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.\n\nMetadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on a Tilled [Customer](https://api.tilled.com) object. Metadata is not used by Tilled—for example, not used to authorize or decline a charge—and won't be seen by your users unless you choose to show it to them. Do not store any sensitive information (bank account numbers, card details, etc.) as metadata.\n\n# Apple Pay\n\nTilled supports Apple Pay through the Tilled.js [`PaymentRequest`](https://docs.tilled.com/tilledjs/#paymentrequest-ie-apple-pay) object.\n\nIn order to start accepting payments with Apple Pay, you will first need to validate the domains you plan to host the Apple Pay Button on by:\n\n- Hosting Tilled's Apple Domain Verification File on the domain\n- Use the Tilled API to register the domain\n\n## Domain Verification File\n\nDomains hosting an Apple Pay Button must be secured with HTTPS (TLS 1.2 or later) and have a valid SSL certificate.\n\nBefore [registering your domain](https://api.tilled.com) with the Tilled API, you need to host Tilled's [Apple Domain Verification File](https://api.tilled.com/apple-developer-merchantid-domain-association) on the domain at the path: `/.well-known/apple-developer-merchantid-domain-association`\n\n# Tilled.js\n\nTilled.js is the easiest way to get started collecting payments. It allows you to embed a payments form in your application and stores credit card information securely on remote servers instead of passing through your network. View the documentation [here](https://docs.tilled.com/tilledjs/).\n\n# Webhooks\n\n## Receive event notifications with webhooks\n\nListen for events on your Tilled account so your integration can automatically trigger reactions.\n\nTilled uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a customer’s bank confirms a payment, a customer disputes a charge, or a recurring payment succeeds.\n\nBegin using webhooks with your Tilled integration in just a couple steps:\n\n- Create a webhook endpoint on your server.\n- Register the endpoint with Tilled to go live.\n\nNot all Tilled integrations require webhooks. Keep reading to learn more about what webhooks are and when you should use them.\n\n### What are webhooks\n\n_Webhooks_ refers to a combination of elements that collectively create a notification and reaction system within a larger integration.\n\nMetaphorically, webhooks are like a phone number that Tilled calls to notify you of activity in your Tilled account. The activity could be the creation of a new customer or the payout of funds to your bank account. The webhook endpoint is the person answering that call who takes actions based upon the specific information it receives.\n\nNon-metaphorically, the webhook endpoint is just more code on your server, which could be written in Ruby, PHP, Node.js, or whatever. The webhook endpoint has an associated URL (e.g., https://example.com/webhooks). The Tilled notifications are Event objects. This Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. The webhook endpoint uses the event details to take any required actions, such as indicating that an order should be fulfilled.\n\n### When to use webhooks\n\nMany events that occur within a Tilled account have synchronous results–immediate and direct–to an executed request. For example, a successful request to create a customer immediately returns a Customer object. Such requests don’t require webhooks, as the key information is already available.\n\nOther events that occur within a Tilled account are asynchronous: happening at a later time and not directly in response to your code’s execution. Most commonly these involve:\n\n- The [Payment Intents API](https://api.tilled.com)\n\nWith these and similar APIs, Tilled needs to notify your integration about changes to the status of an object so your integration can take subsequent steps.\n\nThe specific actions your webhook endpoint may take differs based upon the event. Some examples include:\n\n- Updating a customer’s membership record in your database when a subscription payment succeeds\n- Logging an accounting entry when a transfer is paid\n- Indicating that an order can be fulfilled (i.e., boxed and shipped)\n\n## Verifying signatures manually\n\nThe `tilled-signature` header included in each signed event contains a timestamp and one or more signatures. The timestamp is prefixed by `t=`, and each signature is prefixed by a `scheme`. Schemes start with `v`, followed by an integer. Currently, the only valid live signature scheme is `v1`.\n\n```\ntilled-signature:t=1614049713663,v1=8981f5902896f479fa9079eec71fca01e9a065c5b59a96b221544023ce994b02\n```\n\nTilled generates signatures using a hash-based message authentication code ([HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)) with [SHA-256](https://en.wikipedia.org/wiki/SHA-2). You should ignore all schemes that are not `v1`.\n\nYou can verify the webhook event signature by following these steps.\n\n### Step 1: Extract the timestamp and signatures from the header\n\nSplit the header, using the `,` character as the separator, to get a list of elements. Then split each element, using the `=` character as the separator, to get a prefix and value pair.\n\nThe value for the prefix `t` corresponds to the timestamp, and `v1` corresponds to the signature (or signatures). You can discard all other elements.\n\n### Step 2: Prepare the signed_payload string\n\nThe `signed_payload` string is created by concatenating:\n\n- The timestamp (as a string)\n- The character `.`\n- The actual JSON payload (i.e., the request body)\n\n### Step 3: Determine the expected signature\n\nCompute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the `signed_payload` string as the message.\n\n### Step 4: Compare the signatures\n\nCompare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.\n\nTo protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.\n",
  "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/tilled.com/main/1.0/apis.json",
  "tags": [
    "tilled.com",
    "main"
  ],
  "created": "2026-04-03",
  "modified": "2026-04-03",
  "specificationVersion": "0.19",
  "access": "3rd-Party",
  "maintainers": [
    {
      "FN": "Jentic",
      "X-github": "jentic",
      "url": "https://github.com/jentic"
    }
  ],
  "apis": [
    {
      "aid": "tilled.com:main-1.0",
      "name": "Tilled API",
      "description": "The Tilled API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer).\nOur API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\nYou can use the Tilled API in test mode, which does not affect your live data or interact with the banking networks.\nThe API key you use to authenticate the request determines whether the request is live mode or test mode.\nBefore your account is activated you will only be able to interact with test mode.\n\nAuthentication uses a standard web token schema.\n\n**Notice**: The Tilled API treats HTTP status `401` to mean `Unauthenticated`\nand not the HTTP standard name of `Unauthorized`.\nRequests made for materials the requester does not have permission to access, the API will respond with `403: Forbidden`.\n\n# Authentication\n\nThe tilled API uses API keys to authenticate requests. You can view and manage your API keys in the\nTilled Dashboard.\n\nTest mode secret keys have the prefix sk*test* and live mode secret keys have the prefix sk*live*.\nAlternatively, you can use restricted API keys for granular permissions.\n\nYour API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys\nin publicly accessible areas such as GitHub, client-side code, and so forth.\n\nAuthentication to the API is performed via custom HTTP Header `tilled-api-key`. Provide your API key as the value.\n\nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests\nwithout authentication will also fail.\n\n<!-- ReDoc-Inject: <security-definitions> -->\n\n# Errors\n\nTilled uses conventional HTTP response codes to indicate the success or failure of an API request.\nIn general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error\nthat failed given the information provided (e.g., a required parameter was omitted, a charge failed,\netc.). Codes in the `5xx` range indicate an error with Tilled's servers (these are rare).\n\nSome `4xx` errors that could be handled programmatically (e.g., a card is declined)\ninclude an error code that briefly explains the error reported.\n\n# Request IDs\n\nEach API request has an associated request identifier. You can find this value in the response headers, under `request-id`. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.\n\n# Metadata\n\nUpdatable Tilled objects—including [Account](https://api.tilled.com), [Customer](https://api.tilled.com), [PaymentIntent](https://api.tilled.com), [Refund](https://api.tilled.com), and [Subscription](https://api.tilled.com)—have a `metadata` parameter. You can use this parameter to attach key-value data to these Tilled objects.\n\nYou can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.\n\nMetadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on a Tilled [Customer](https://api.tilled.com) object. Metadata is not used by Tilled—for example, not used to authorize or decline a charge—and won't be seen by your users unless you choose to show it to them. Do not store any sensitive information (bank account numbers, card details, etc.) as metadata.\n\n# Apple Pay\n\nTilled supports Apple Pay through the Tilled.js [`PaymentRequest`](https://docs.tilled.com/tilledjs/#paymentrequest-ie-apple-pay) object.\n\nIn order to start accepting payments with Apple Pay, you will first need to validate the domains you plan to host the Apple Pay Button on by:\n\n- Hosting Tilled's Apple Domain Verification File on the domain\n- Use the Tilled API to register the domain\n\n## Domain Verification File\n\nDomains hosting an Apple Pay Button must be secured with HTTPS (TLS 1.2 or later) and have a valid SSL certificate.\n\nBefore [registering your domain](https://api.tilled.com) with the Tilled API, you need to host Tilled's [Apple Domain Verification File](https://api.tilled.com/apple-developer-merchantid-domain-association) on the domain at the path: `/.well-known/apple-developer-merchantid-domain-association`\n\n# Tilled.js\n\nTilled.js is the easiest way to get started collecting payments. It allows you to embed a payments form in your application and stores credit card information securely on remote servers instead of passing through your network. View the documentation [here](https://docs.tilled.com/tilledjs/).\n\n# Webhooks\n\n## Receive event notifications with webhooks\n\nListen for events on your Tilled account so your integration can automatically trigger reactions.\n\nTilled uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a customer’s bank confirms a payment, a customer disputes a charge, or a recurring payment succeeds.\n\nBegin using webhooks with your Tilled integration in just a couple steps:\n\n- Create a webhook endpoint on your server.\n- Register the endpoint with Tilled to go live.\n\nNot all Tilled integrations require webhooks. Keep reading to learn more about what webhooks are and when you should use them.\n\n### What are webhooks\n\n_Webhooks_ refers to a combination of elements that collectively create a notification and reaction system within a larger integration.\n\nMetaphorically, webhooks are like a phone number that Tilled calls to notify you of activity in your Tilled account. The activity could be the creation of a new customer or the payout of funds to your bank account. The webhook endpoint is the person answering that call who takes actions based upon the specific information it receives.\n\nNon-metaphorically, the webhook endpoint is just more code on your server, which could be written in Ruby, PHP, Node.js, or whatever. The webhook endpoint has an associated URL (e.g., https://example.com/webhooks). The Tilled notifications are Event objects. This Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. The webhook endpoint uses the event details to take any required actions, such as indicating that an order should be fulfilled.\n\n### When to use webhooks\n\nMany events that occur within a Tilled account have synchronous results–immediate and direct–to an executed request. For example, a successful request to create a customer immediately returns a Customer object. Such requests don’t require webhooks, as the key information is already available.\n\nOther events that occur within a Tilled account are asynchronous: happening at a later time and not directly in response to your code’s execution. Most commonly these involve:\n\n- The [Payment Intents API](https://api.tilled.com)\n\nWith these and similar APIs, Tilled needs to notify your integration about changes to the status of an object so your integration can take subsequent steps.\n\nThe specific actions your webhook endpoint may take differs based upon the event. Some examples include:\n\n- Updating a customer’s membership record in your database when a subscription payment succeeds\n- Logging an accounting entry when a transfer is paid\n- Indicating that an order can be fulfilled (i.e., boxed and shipped)\n\n## Verifying signatures manually\n\nThe `tilled-signature` header included in each signed event contains a timestamp and one or more signatures. The timestamp is prefixed by `t=`, and each signature is prefixed by a `scheme`. Schemes start with `v`, followed by an integer. Currently, the only valid live signature scheme is `v1`.\n\n```\ntilled-signature:t=1614049713663,v1=8981f5902896f479fa9079eec71fca01e9a065c5b59a96b221544023ce994b02\n```\n\nTilled generates signatures using a hash-based message authentication code ([HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)) with [SHA-256](https://en.wikipedia.org/wiki/SHA-2). You should ignore all schemes that are not `v1`.\n\nYou can verify the webhook event signature by following these steps.\n\n### Step 1: Extract the timestamp and signatures from the header\n\nSplit the header, using the `,` character as the separator, to get a list of elements. Then split each element, using the `=` character as the separator, to get a prefix and value pair.\n\nThe value for the prefix `t` corresponds to the timestamp, and `v1` corresponds to the signature (or signatures). You can discard all other elements.\n\n### Step 2: Prepare the signed_payload string\n\nThe `signed_payload` string is created by concatenating:\n\n- The timestamp (as a string)\n- The character `.`\n- The actual JSON payload (i.e., the request body)\n\n### Step 3: Determine the expected signature\n\nCompute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the `signed_payload` string as the message.\n\n### Step 4: Compare the signatures\n\nCompare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.\n\nTo protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.\n",
      "image": "https://docs.tilled.com/images/api_logo.png",
      "baseURL": "https://api.tilled.com",
      "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/tilled.com/main/1.0",
      "version": "1.0",
      "tags": [
        "tilled.com",
        "main"
      ],
      "properties": [
        {
          "type": "OpenAPI",
          "name": "OpenAPI definition",
          "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/tilled.com/main/1.0/openapi.json",
          "mediaType": "application/openapi+json"
        },
        {
          "type": "GitHubRepo",
          "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/tilled.com/main/1.0"
        }
      ],
      "contact": [
        {
          "FN": "Tilled API Support",
          "email": "integrations@tilled.com",
          "url": "https://www.tilled.com/contact-us/"
        }
      ]
    }
  ]
}