API Basics


Sunlight provides a powerful and flexible API that allows you to integrate Sunlight's functionality into your application. Whether you're performing card switches, managing customizations, or configuring webhooks, the Sunlight API offers a wide range of capabilities to enhance your user experience. In this guide, we'll provide a high-level overview of how to work with Sunlight APIs, including authentication, versioning, and error handling.


All Sunlight API requests require authentication using an API key and a secret key. These keys are used to identify and authorize your application when making requests to the Sunlight API.

To obtain your API credentials, please reach out to us at [email protected]

When making an API request, you must include the following headers for authentication:

"x-api-key: YOUR_API_KEY"
"x-secret-key: YOUR_SECRET_KEY"

Additionally, you need to specify the API version you wish to use. The default version is 1. Use the following header to specify the version:

"x-version: 1"


Here's an example of an authenticated API request using curl:

curl --request GET \
     --url https://api.sunlightapi.com/api/customizations/list \
     --header 'accept: application/json' \
     --header 'x-api-key: <YOUR-API-KEY>' \
     --header 'x-secret-key: <YOUR-SECRET-KEY>' \
     --header 'x-version: 1'

Error Handling

When working with the Sunlight API, it's important to handle errors appropriately. The API may return error responses with specific error codes and messages. The error response is provided in JSON format with the following structure:

  "error_code": string,
  "error_message": string

Below, we've grouped the possible error responses by their corresponding HTTP status codes. Each error is described by its error_code and error_message.

400 Bad Request

Error CodeError Message
1001api key header is missing
1002secret key header is missing
1003version header is missing
1010endpoint not found for the specified version
1030invalid input parameters

401 Unauthorized

Error CodeError Message
1006invalid api key
1007invalid secret key
1011inactive endpoint
1012customer not found

429 Too Many Requests

Error CodeError Message
1020daily quota limit exceeded

You can use this information to diagnose failed transactions and fine-tune your exception-handling capabilities. By understanding the different error codes and messages, you can provide meaningful feedback to users and handle errors gracefully in your application.

Versioning and Backwards Compatibility

The Sunlight API is designed with versioning and backwards compatibility in mind. We strive to avoid making breaking changes to the API without reaching out to you first. We're continually making backwards-compatible changes to the API. Examples of things we do not consider "breaking" include:

  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Adding new API resources or methods.
  • Changing the length or format of opaque strings, such as resource IDs, error messages, and other human-readable strings.

What’s Next

By following these API basics, you can effectively work with the Sunlight API and take advantage of its powerful features. As you continue to explore the capabilities of the Sunlight API, be sure to review the full API documentation and guides for additional information on how to leverage the various endpoints and features available.