---
title: "Shopify Credits Sync"
method: POST
path: "/api/internal/shopify-credits-sync"
tags: ["internal"]
---

# Shopify Credits Sync

`POST /api/internal/shopify-credits-sync`

## Request

- Base URL: `https://api.tintin-x.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tintin-x.com/api/internal/shopify-credits-sync`
- Auth: none declared

Ensure the shop's headless user + wallet, apply the plan's credit
grant, and return the current balance. The Shopify app calls this on
every load (cheap). Grant shape depends on the plan:

- ``free``: a ONE-TIME signup grant into the non-expiring bonus pool
  (``add_studio_bonus_credits``, action_type ``shopify_signup_free``) —
  fired only if this shop has never received a free grant (neither the
  signup grant nor a legacy ``shopify_free_monthly`` from the pre-billing
  era). Never refilled: once spent, the merchant upgrades or stops.
- ``starter``: a monthly lazy reset of the subscription
  ``studio_credits`` pool via ``grant_studio_credits`` (SET + expiry on
  the 1st) — fires when the current grant has lapsed, so mid-month
  consumption is preserved. On upgrade the app passes ``force=true``
  once so the paid allotment takes effect immediately; downgrades don't
  force, so a paid month's balance survives until the 1st, after which
  the free plan grants nothing further.

A Shopify shop account never has a Stripe studio subscription (synthetic
email, no login), so the subscription pool isn't contended. Idempotent on
``email`` (like provision-user). X-Internal-Key gated.

## Request body

- ShopifyCreditsSyncRequest
  - `email` string, required
  - `monthly_credits` integer
  - `plan` string
  - `force` boolean

## Response `200`

Successful Response

- ShopifyCreditsSyncResponse
  - `user_id` string, required
  - `created` boolean, required
  - `granted` boolean, required
  - `balance_credits` number, required
  - `balance_centicredits` integer, required
  - `next_reset_at` string, nullable, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tintin-x/apis/tintin-api.md) · [All operations](https://skmtc.dev/tintin-x/apis/tintin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tintin-x/apis/tintin-api/revisions/8839a8d0a66c?raw)