Getting Started
Welcome to the Gooten API Documentation!
Our API is organized around REST and contains predictable, resource-oriented URLs. We use common HTTP methods such as GET
, POST
, PUT
and DELETE
which can be understood and used by off-the-shelf HTTP clients. We also support cross-origin resource sharing (CORS) which allows you to interact securely with our API from a client-side web application.
With the use of our API, your developers have extensive access to Gooten's core features. Check out some of the things and resources that you can work with using our API.
Manage Orders- Submit orders from your custom websites.
- Search your orders in Gooten.
- Update the order status in Gooten.
- Receive order status updates via Webhooks in Gooten.
- Get available product information (catalog, descriptions, SKUs, options, image templates) so that you can render them on your custom website.
- Connect your images with Gooten products to create Print Ready Products to allow future ordering.
- Update your Print Ready Products.
- Delete your Print Ready Products.
- Generate Product Previews
- Use the Price Estimate API to get the prices of items in the cart.
- Use the Address Validation API to validate addresses when checking out.
- Use the Shipping Options API to get the available shipping options.
- Use the Shipping Price Estimate API to get the shipping prices.
Authentication
Each API request to the Gooten API must have the RecipeID
parameter included in the URL.
You authenticate to the Gooten API by providing your RecipeID
. For the Orders Method, you may also need to provide a secret API key (PartnerBillingKey
).
- The
RecipeID
is a unique key value that represents your ID within Gooten. This is a public key. - The
PartnerBillingKey
is a unique private key that is used for order submission on your behalf. This key should not be exposed.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
Error Handling
Anytime an error occurs from an API request, the JSON response returns with HadError=true
as well as the reason why. For example, let's say that you tried to submit an order without a postal/zip code. The server’s response would look as follows:
{
"ErrorReferenceCode": "72f3c717-f204-4b4a-9b14-7c169f346235",
"Errors": [
{
"AttemptedValue": "",
"CustomState": null,
"ErrorMessage": "'Postal Code' should not be empty.",
"PropertyName": "Order.ShipToAddress.PostalCode"
}
],
"HadError": true
}
Therefore, we recommend checking each response to see if includes a HadError=true
value in order to ascertain if an error occurred.
Since all errors are assigned IDs, anytime a user is having an issue that they can’t figure out its possible for us to look up exactly what happened during the request.
In general, 5xx indicates an error on Gooten’s end, 4xx means there was a response validation issue, and 2xx indicates success. Not all errors map cleanly onto HTTP response codes, however.
Please utilize the human-readable message if available and additional response values with more details about the error to assist in solving.