Skip to main content

Getting started

The Submarine GraphQL API covers every entity and operation in the Submarine Platform: channels, customers, products, subscriptions, presales, crowdfunding campaigns, payments and more. A single federated GraphQL API serves all of it.

You can call the API in two contexts:

  • Channel context. An integrator acts for a merchant's store and can reach that store's data.
  • Customer context. A storefront or customer account acts for a single customer and can only reach that customer's own records.

Authentication explains how each context authenticates.

These guides assume you know the basics of GraphQL. If you don't, start with the introduction to GraphQL.

Endpoint​

The API has a single endpoint for every operation:

https://api.submarineplatform.com/graphql

Send each operation as a POST request with a JSON body containing a query and, optionally, variables and operationName.

Your first request​

Every operation except schema introspection needs an API key. Authentication explains where to find yours.

curl -X POST https://api.submarineplatform.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SUBMARINE_API_KEY" \
  -d '{"query": "query { __typename }"}'

A successful response confirms your API key works:

{ "data": { "__typename": "Query" } }

From there, explore the API Reference. It's generated from the live schema and grouped by domain.

Introspection​

Schema introspection doesn't need an API key, so GraphQL tooling (codegen, IDE plugins, Postman, Insomnia) can discover the schema. The operation must be named IntrospectionQuery, which is the default for most tools.

Query limits​

The API limits how expensive each query is. It doesn't limit how many requests you send. Each Submarine service checks its part of a query against two limits.

The first is complexity. Every field you select costs a point. Fields inside a connection cost a point for each item on the page, so the page size you ask for with first or last multiplies them. Asking for large pages of deeply selected data is the quickest way to reach the limit.

The second is depth: how far the query nests, from the top-level field down to the deepest selection.

The API doesn't run a query that exceeds either limit. It returns a top-level error naming the limit instead. To stay under the limits, select only the fields you need and page through large lists. Pagination explains how.

IDs​

Submarine identifies resources by global ID, which names the resource type and its ID:

gid://submarine/Customer/0184e072-e87a-1519-6026-0bc25dbd9109

Arguments typed SharedGlobalID also accept an external ID. That's the ID of the same resource in the merchant's e-commerce platform, such as a Shopify customer ID. Replace submarine with external and use the external ID:

gid://external/Customer/6204442509552

Both IDs find the same customer. The API looks up external IDs within the channel you're authenticated as.

Errors​

Most errors come back with HTTP 200 OK, so check the response body as well as the status code.

  • Invalid queries. The API validates every query against the schema before running it. It doesn't run an invalid query. It returns a top-level errors list with the message, location and path of each problem.
  • Query limits. A query over a query limit also returns a top-level error.
  • Not found. Querying a resource that doesn't exist returns null in place of the resource. So does querying a record outside your context, such as another customer's subscription.
  • Mutation errors. A mutation can pass validation and still break a business rule. Every mutation payload has a userErrors list for this. Each entry has a message and a field path to the input that caused it. Check userErrors on every mutation response.
  • Authentication errors. A request without a valid API key fails before it reaches any Submarine service. Authentication shows the response.

Request IDs​

Every response carries an X-Request-Id header. Quote it when you contact Submarine about a request.

Versioning​

The API isn't versioned. The API Reference flags deprecated fields. Avoid them in new integrations.

Status and support​

Check health.getsubmarine.com for the API's current status. For help, email hello@getsubmarine.com.