Contact Sales
Search

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.

Manage Products
  • 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

Build your own custom cart (Gooten does not collect any payments from your customers)
  • 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.

We highly recommend that you read the next section on Authentication before trying to utilize our APIs.

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.

You can manage and view your API Keys from your account settings page in our API Settings in the Gooten Admin Panel.

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.

Next Step: Getting user’s location