postman_collection.json

{
  "auth": {
    "bearer": [
      {
        "key": "token",
        "type": "string",
        "value": "{{apiKey}}"
      }
    ],
    "type": "bearer"
  },
  "info": {
    "description": "## Fast start\n\nRun the first public demo for a real unmetered result. Then request a key, paste the emailed token into `claimToken`, and claim once; the claim test stores `apiKey` and clears `claimToken` locally. Saved 200 examples are produced by a pinned local execution of the same engine.\n\n## Errors\n\n`401` means a missing, invalid, or revoked API key. The service uses `400 invalid_request`, not 422. On `429`, branch on `error.code`, honor `Retry-After`, and back off. Every committed secret-bearing variable is empty.",
    "name": "DemandGraph API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test('customer-ready demo contract', function () {",
              "  pm.response.to.have.status(200);",
              "  const b = pm.response.json();",
              "  pm.expect(b.count).to.eql(1);",
              "  pm.expect(b.scores[0].trend).to.eql('accelerating');",
              "  pm.expect(b.scores[0].confidence).to.be.a('number');",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "name": "Public demo — scores one topic without a key",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"topics\": [\n    {\n      \"topic\": \"mcp servers\",\n      \"points\": [\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 1200\n        },\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-07-01T00:00:00Z\",\n          \"value\": 2100\n        },\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 4800\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 340\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-07-01T00:00:00Z\",\n          \"value\": 910\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 2400\n        },\n        {\n          \"source\": \"employment\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 12\n        },\n        {\n          \"source\": \"employment\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 47\n        }\n      ]\n    }\n  ]\n}"
        },
        "description": "Run first. The first useful result is the combination of `trend`, `momentum`, `commercialIntent`, and `confidence`: it tells a product team that this supplied series is accelerating, while making the evidence depth visible instead of pretending DemandGraph collected the data. Nothing is stored or metered; the payload is synthetic.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "demo",
            "score"
          ],
          "raw": "{{baseUrl}}/v1/demo/score"
        }
      },
      "response": [
        {
          "_postman_previewlanguage": "json",
          "body": "{\n  \"count\": 1,\n  \"scores\": [\n    {\n      \"topic\": \"mcp servers\",\n      \"momentum\": 100,\n      \"acceleration\": 11.5,\n      \"commercialIntent\": 42.9,\n      \"durability\": 100,\n      \"trend\": \"accelerating\",\n      \"sourceCount\": 3,\n      \"breakdown\": [\n        {\n          \"source\": \"developer\",\n          \"points\": 3,\n          \"changePct\": 605.9,\n          \"weight\": 0.7\n        },\n        {\n          \"source\": \"employment\",\n          \"points\": 2,\n          \"changePct\": 291.7,\n          \"weight\": 0.9\n        },\n        {\n          \"source\": \"search\",\n          \"points\": 3,\n          \"changePct\": 300,\n          \"weight\": 0.5\n        }\n      ],\n      \"confidence\": 84,\n      \"windowStart\": \"2026-06-01T00:00:00.000Z\",\n      \"windowEnd\": \"2026-08-01T00:00:00.000Z\"\n    }\n  ],\n  \"requestId\": \"req_example\"\n}",
          "code": 200,
          "cookie": [],
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "name": "200 — first useful result",
          "originalRequest": {
            "auth": {
              "type": "noauth"
            },
            "body": {
              "mode": "raw",
              "options": {
                "raw": {
                  "language": "json"
                }
              },
              "raw": "{\n  \"topics\": [\n    {\n      \"topic\": \"mcp servers\",\n      \"points\": [\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 1200\n        },\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-07-01T00:00:00Z\",\n          \"value\": 2100\n        },\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 4800\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 340\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-07-01T00:00:00Z\",\n          \"value\": 910\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 2400\n        },\n        {\n          \"source\": \"employment\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 12\n        },\n        {\n          \"source\": \"employment\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 47\n        }\n      ]\n    }\n  ]\n}"
            },
            "description": "Run first. The first useful result is the combination of `trend`, `momentum`, `commercialIntent`, and `confidence`: it tells a product team that this supplied series is accelerating, while making the evidence depth visible instead of pretending DemandGraph collected the data. Nothing is stored or metered; the payload is synthetic.",
            "header": [
              {
                "key": "content-type",
                "value": "application/json"
              }
            ],
            "method": "POST",
            "url": {
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "demo",
                "score"
              ],
              "raw": "{{baseUrl}}/v1/demo/score"
            }
          },
          "status": "OK"
        }
      ]
    },
    {
      "name": "Request a free sandbox API key (sends a verification email)",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"email\": \"you@example.com\",\n  \"name\": \"postman\",\n  \"source\": {\n    \"source\": \"postman\",\n    \"medium\": \"collection\",\n    \"campaign\": \"demandgraph-postman\",\n    \"content\": \"public-collection\"\n  }\n}"
        },
        "description": "Returns 202 and emails a one-time claim token; it never returns an API key. The source tuple is the exact Postman attribution for this collection.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys"
          ],
          "raw": "{{baseUrl}}/v1/keys"
        }
      }
    },
    {
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "if (pm.response.code === 201) {",
              "  const b = pm.response.json();",
              "  pm.collectionVariables.set('apiKey', b.apiKey);",
              "  pm.collectionVariables.set('keyId', b.keyId);",
              "  pm.collectionVariables.set('claimToken', '');",
              "}"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "name": "Exchange an emailed claim token for the API key",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"token\": \"{{claimToken}}\"\n}"
        },
        "description": "Paste the emailed token into claimToken and run once. On 201, this test stores apiKey/keyId locally and clears claimToken.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys",
            "claim"
          ],
          "raw": "{{baseUrl}}/v1/keys/claim"
        }
      }
    },
    {
      "name": "Score and rank topics by demand momentum",
      "request": {
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"topics\": [\n    {\n      \"topic\": \"mcp servers\",\n      \"points\": [\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 1200\n        },\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-07-01T00:00:00Z\",\n          \"value\": 2100\n        },\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 4800\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 340\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-07-01T00:00:00Z\",\n          \"value\": 910\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 2400\n        },\n        {\n          \"source\": \"employment\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 12\n        },\n        {\n          \"source\": \"employment\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 47\n        }\n      ]\n    }\n  ]\n}"
        },
        "description": "Authenticated primary-value call. Reuses the complete demo payload. Supply at least two dated observations per topic. Values are unitless within a source; DemandGraph compares relative change and does not acquire or resell signal data.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          },
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "scores"
          ],
          "raw": "{{baseUrl}}/v1/scores"
        }
      },
      "response": [
        {
          "_postman_previewlanguage": "json",
          "body": "{\n  \"count\": 1,\n  \"scores\": [\n    {\n      \"topic\": \"mcp servers\",\n      \"momentum\": 100,\n      \"acceleration\": 11.5,\n      \"commercialIntent\": 42.9,\n      \"durability\": 100,\n      \"trend\": \"accelerating\",\n      \"sourceCount\": 3,\n      \"breakdown\": [\n        {\n          \"source\": \"developer\",\n          \"points\": 3,\n          \"changePct\": 605.9,\n          \"weight\": 0.7\n        },\n        {\n          \"source\": \"employment\",\n          \"points\": 2,\n          \"changePct\": 291.7,\n          \"weight\": 0.9\n        },\n        {\n          \"source\": \"search\",\n          \"points\": 3,\n          \"changePct\": 300,\n          \"weight\": 0.5\n        }\n      ],\n      \"confidence\": 84,\n      \"windowStart\": \"2026-06-01T00:00:00.000Z\",\n      \"windowEnd\": \"2026-08-01T00:00:00.000Z\"\n    }\n  ],\n  \"requestId\": \"req_example\"\n}",
          "code": 200,
          "cookie": [],
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "name": "200 — authenticated primary result shape",
          "originalRequest": {
            "body": {
              "mode": "raw",
              "options": {
                "raw": {
                  "language": "json"
                }
              },
              "raw": "{\n  \"topics\": [\n    {\n      \"topic\": \"mcp servers\",\n      \"points\": [\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 1200\n        },\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-07-01T00:00:00Z\",\n          \"value\": 2100\n        },\n        {\n          \"source\": \"search\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 4800\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 340\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-07-01T00:00:00Z\",\n          \"value\": 910\n        },\n        {\n          \"source\": \"developer\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 2400\n        },\n        {\n          \"source\": \"employment\",\n          \"at\": \"2026-06-01T00:00:00Z\",\n          \"value\": 12\n        },\n        {\n          \"source\": \"employment\",\n          \"at\": \"2026-08-01T00:00:00Z\",\n          \"value\": 47\n        }\n      ]\n    }\n  ]\n}"
            },
            "description": "Authenticated primary-value call. Reuses the complete demo payload. Supply at least two dated observations per topic. Values are unitless within a source; DemandGraph compares relative change and does not acquire or resell signal data.",
            "header": [
              {
                "key": "content-type",
                "value": "application/json"
              },
              {
                "key": "authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "method": "POST",
            "url": {
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "scores"
              ],
              "raw": "{{baseUrl}}/v1/scores"
            }
          },
          "status": "OK"
        }
      ]
    },
    {
      "name": "The default source weights, and why they differ",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "description": "Public stable-code catalogue. Use codes and constants for integrations; prose details may be reworded.",
        "header": [],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "weights"
          ],
          "raw": "{{baseUrl}}/v1/weights"
        }
      }
    },
    {
      "name": "Liveness and deployed version",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "header": [],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "health"
          ],
          "raw": "{{baseUrl}}/health"
        }
      }
    },
    {
      "name": "Service index — endpoints, auth and error format",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "header": [],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [],
          "raw": "{{baseUrl}}/"
        }
      }
    },
    {
      "name": "Start a hosted Square checkout for a paid tier",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"tier\": \"developer\"\n}"
        },
        "description": "Returns a Square-hosted payment URL for the requested tier. No API key is needed — a prospect has not got one yet. The email Square collects becomes the account, so a key issued later for the same address inherits the paid quota. Enterprise returns a contact route rather than a payment link. THIS IS THE PATH FOR SOMEONE WHO IS NOT YET PAYING. It starts a NEW Square recurring subscription, so it is refused with 409 `conflict` (`details.reason` `existing_subscription`) when the request carries a dashboard session for an account that already has a live plan on this API — a second subscription would be charged alongside the first, every month, and this API cannot cancel either one. Change tier with POST /v1/subscription/plan, or, when Square collects your base fee, cancel it with Square first.\n\nPostman authentication: No Auth. This public checkout bootstrap must not inherit the collection API key.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "checkout"
          ],
          "raw": "{{baseUrl}}/v1/checkout"
        }
      }
    },
    {
      "name": "Square billing events, forwarded by the shared hub",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "description": "Machine-to-machine only. The shared Square billing hub POSTs signed events here; the signature is verified over the exact request bytes. Not callable by API consumers — documented so the integration is auditable.\n\nMachine-to-machine only. Postman uses No Auth so bearer credentials cannot leak onto this request. An authorized hub must set local `hubTimestamp` and `hubSignature`, where the signature is HMAC-SHA256 over `${x-hub-timestamp}.${rawBody}` with the shared hub secret. Both committed placeholders are empty.",
        "header": [
          {
            "description": "Machine-to-machine HMAC-SHA256 signature. Empty in the committed collection; never use an API key here.",
            "key": "x-hub-signature",
            "type": "text",
            "value": "{{hubSignature}}"
          },
          {
            "description": "Unix timestamp covered by the hub signature and five-minute replay window. Empty in the committed collection.",
            "key": "x-hub-timestamp",
            "type": "text",
            "value": "{{hubTimestamp}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "billing",
            "webhook"
          ],
          "raw": "{{baseUrl}}/api/billing/webhook"
        }
      }
    },
    {
      "name": "List your API keys for this API",
      "request": {
        "description": "Every key on YOUR account for this API — label, non-secret prefix, status, when it was created, when it was last used, and what it has consumed this period. Authenticate with any active key on the account; the account is taken from that key, never from a parameter, so this can only ever return your own keys. Keys you hold for other APIs in the portfolio are not listed here. Secrets are not returned and cannot be: only a peppered hash is stored. Free, and consumes no quota.",
        "header": [
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys"
          ],
          "raw": "{{baseUrl}}/v1/keys"
        }
      }
    },
    {
      "name": "Revoke one of your API keys",
      "request": {
        "description": "Kills a key immediately: the very next request made with it is refused with 401 invalid_api_key. There is no propagation delay and no cache to wait out. You may revoke the key you are authenticating with — that is the correct move when it has leaked, though you will then need another key, or the email flow, to get back in; rotate does both in one call. A key belonging to another account, or to another API, answers 404 exactly as an unknown id does, so this cannot be used to probe for keys you do not own. Idempotent, and free.",
        "header": [
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys",
            "{{keyId}}",
            "revoke"
          ],
          "raw": "{{baseUrl}}/v1/keys/{{keyId}}/revoke"
        }
      }
    },
    {
      "name": "Replace one of your API keys with a new secret",
      "request": {
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"name\": \"production (rotated)\"\n}"
        },
        "description": "Issues a replacement key and revokes the old one. This is the answer to a leaked or lost key: the new secret is returned once, the old secret stops working immediately, and the label carries over unless you supply a new one. The replacement is issued at your account's current allowance — your paid plan if you have one — not at the old key's. Rotating does not count against the active-key limit, because it replaces rather than adds. Free, and it works while you are out of quota.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          },
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "keys",
            "{{keyId}}",
            "rotate"
          ],
          "raw": "{{baseUrl}}/v1/keys/{{keyId}}/rotate"
        }
      }
    },
    {
      "name": "Your consumption and remaining allowance for this period",
      "request": {
        "description": "Reports what YOUR ACCOUNT has consumed in the current quota period, the ceiling being enforced against it, and when that ceiling resets. The allowance belongs to the account, not to a key: every key you hold for this API draws on the same budget, so \"used\" is the total across all of them and a new key does not arrive with a fresh one. Free, and it consumes no quota, so it still answers once you are getting 429 quota_exceeded — which is the point: compare \"used\" against \"ceiling\" and read \"period.resetsAt\" to tell a period you have simply exhausted from a plan that is no longer active, which shows as a \"status\" of canceled and a ceiling of 0. \"used\" counts billing units (see \"unit\"), not HTTP requests: a single request can consume several. All money is in integer minor units (cents), never a decimal. The period reported here is the quota period — the calendar month in UTC, resetting at 00:00 UTC on the 1st. Your invoice window is anchored to the date you subscribed and is a different window; the amounts here are what this period’s usage has accrued so far, not a bill.",
        "header": [
          {
            "key": "authorization",
            "value": "Bearer {{apiKey}}"
          }
        ],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "usage"
          ],
          "raw": "{{baseUrl}}/v1/usage"
        }
      }
    },
    {
      "name": "Your current plan, billing window and available changes (dashboard session required)",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "description": "Reports the plan this account is on, the billing window it is in, any tier change already staged for the next invoice, and the full pricing ladder marked up so you can see which rungs are an upgrade and which a downgrade. `planChangesGoThrough` is the field to branch on: `self_serve` means POST /v1/subscription/plan can move you; `provider_managed` means Square’s own recurring subscription holds your price and neither this API nor a new checkout can move it — buying again would create a SECOND Square subscription and charge you twice; `checkout` appears only when you have no plan at all, where starting one is exactly right. All money is in integer minor units (cents). AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.\n\nPostman: use No Auth and provide the dashboard `sp_session` through the host cookie jar or the local empty-by-default `sessionCookie` placeholder. An API key is rejected.",
        "header": [
          {
            "description": "Dashboard session only. Keep sessionCookie empty in the committed collection; set it locally or use the Postman cookie jar for this host.",
            "key": "Cookie",
            "type": "text",
            "value": "sp_session={{sessionCookie}}"
          }
        ],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "subscription"
          ],
          "raw": "{{baseUrl}}/v1/subscription"
        }
      }
    },
    {
      "name": "Upgrade or downgrade to another plan (dashboard session required)",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"planId\": \"growth\"\n}"
        },
        "description": "Moves this account to another rung of the published pricing ladder and re-derives the ceiling enforced against every API key on it, so an upgrade is usable immediately rather than at the next invoice. The change is STAGED, not overwritten: the current billing window is closed at this instant and priced against the tier that was actually in force for it, and the incoming tier opens the next window with the original billing anniversary preserved. A downgrade therefore never re-prices days you already consumed on the dearer plan. Refused with 409 `conflict` (`details.reason` `provider_owned_base_fee`) when Square’s own recurring subscription holds your price (`baseFeeOwner` is `provider`) — read `planChangesGoThrough` from GET /v1/subscription first. That case cannot be moved from here at all: this API holds no Square subscription of yours to change, and POST /v1/checkout would create a SECOND one and charge you for both. Cancel with Square and buy the tier you want, or contact support. AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.\n\nPostman: use No Auth, provide `sp_session` through the host cookie jar or local `sessionCookie`, and set local `csrfToken` for `x-csrf-token`. Both placeholders are committed empty. An API key is rejected.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          },
          {
            "description": "Dashboard session only. Keep sessionCookie empty in the committed collection; set it locally or use the Postman cookie jar for this host.",
            "key": "Cookie",
            "type": "text",
            "value": "sp_session={{sessionCookie}}"
          },
          {
            "description": "CSRF token paired with the dashboard session. Empty in the committed collection; set locally immediately before the request.",
            "key": "x-csrf-token",
            "type": "text",
            "value": "{{csrfToken}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "subscription",
            "plan"
          ],
          "raw": "{{baseUrl}}/v1/subscription/plan"
        }
      }
    },
    {
      "name": "Cancel this plan and end metered access (dashboard session required)",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "body": {
          "mode": "raw",
          "options": {
            "raw": {
              "language": "json"
            }
          },
          "raw": "{\n  \"acknowledgeProviderBilling\": true\n}"
        },
        "description": "Cancels the plan and drops every API key on this account for this product to a ceiling of 0, so access ends at the moment you cancel rather than at some later date nothing would enforce. The window you cancel in is closed and invoiced first, prorated to that instant: the elapsed share of the base fee plus any overage you accrued, still under the same spend cap. The invoice it writes is returned as `finalInvoice` and appears in GET /v1/invoices. When Square’s own recurring subscription collects your flat monthly fee (`baseFeeOwner` is `provider`) this API cannot stop that charge, so the request is refused with 409 unless you send `acknowledgeProviderBilling: true` — that flag exists so nobody ends up with a ceiling of zero and a live monthly charge without having been told first. AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.\n\nPostman: use No Auth, provide `sp_session` through the host cookie jar or local `sessionCookie`, and set local `csrfToken` for `x-csrf-token`. Both placeholders are committed empty. An API key is rejected.",
        "header": [
          {
            "key": "content-type",
            "value": "application/json"
          },
          {
            "description": "Dashboard session only. Keep sessionCookie empty in the committed collection; set it locally or use the Postman cookie jar for this host.",
            "key": "Cookie",
            "type": "text",
            "value": "sp_session={{sessionCookie}}"
          },
          {
            "description": "CSRF token paired with the dashboard session. Empty in the committed collection; set locally immediately before the request.",
            "key": "x-csrf-token",
            "type": "text",
            "value": "{{csrfToken}}"
          }
        ],
        "method": "POST",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "subscription",
            "cancel"
          ],
          "raw": "{{baseUrl}}/v1/subscription/cancel"
        }
      }
    },
    {
      "name": "Every invoice issued against this account, newest first (dashboard session required)",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "description": "Returns the stored `api_plan_invoices` rows for this account and this API — the rows the billing run actually wrote, never a reconstruction. Each one reconciles against itself: the included allowance and base fee shown are the PRORATED figures applied to that window, `overageMinorRaw` is the uncapped overage and `overageMinorCapped` is what was charged, and `baseChargedMinor` says how much of the base fee this invoice collected — 0 when Square’s recurring subscription had already taken it. An account with no billing history yet gets an empty list and a `note` explaining why, never a fabricated row. AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.\n\nPostman: use No Auth and provide the dashboard `sp_session` through the host cookie jar or the local empty-by-default `sessionCookie` placeholder. An API key is rejected.",
        "header": [
          {
            "description": "Dashboard session only. Keep sessionCookie empty in the committed collection; set it locally or use the Postman cookie jar for this host.",
            "key": "Cookie",
            "type": "text",
            "value": "sp_session={{sessionCookie}}"
          }
        ],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "invoices"
          ],
          "raw": "{{baseUrl}}/v1/invoices"
        }
      }
    },
    {
      "name": "Every payment attempted against this account and how it went (dashboard session required)",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "description": "The money movements behind your invoices, newest first: what was charged, whether it succeeded, and the processor’s payment id when it did. A billing period that came to nothing produces NO row here — it was closed without asking the processor for anything, and listing it would show you a payment that never happened. A failed attempt does appear, with its reason, because that is why an account goes past due. AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.\n\nPostman: use No Auth and provide the dashboard `sp_session` through the host cookie jar or the local empty-by-default `sessionCookie` placeholder. An API key is rejected.",
        "header": [
          {
            "description": "Dashboard session only. Keep sessionCookie empty in the committed collection; set it locally or use the Postman cookie jar for this host.",
            "key": "Cookie",
            "type": "text",
            "value": "sp_session={{sessionCookie}}"
          }
        ],
        "method": "GET",
        "url": {
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "v1",
            "payments"
          ],
          "raw": "{{baseUrl}}/v1/payments"
        }
      }
    }
  ],
  "variable": [
    {
      "key": "baseUrl",
      "type": "string",
      "value": "https://demandgraph-api.com"
    },
    {
      "description": "Set locally after a successful claim. Empty in this committed collection.",
      "key": "apiKey",
      "type": "string",
      "value": ""
    },
    {
      "description": "Paste the one-time emailed token. Cleared locally after a successful claim.",
      "key": "claimToken",
      "type": "string",
      "value": ""
    },
    {
      "description": "Set locally after claim for rotate/revoke operations.",
      "key": "keyId",
      "type": "string",
      "value": ""
    },
    {
      "description": "Dashboard sp_session cookie value. Empty in this committed collection; set locally or use the Postman cookie jar.",
      "key": "sessionCookie",
      "type": "string",
      "value": ""
    },
    {
      "description": "Dashboard CSRF token. Empty in this committed collection; set locally only for a session-authenticated mutation.",
      "key": "csrfToken",
      "type": "string",
      "value": ""
    },
    {
      "description": "Machine-to-machine x-hub-signature value. Empty in this committed collection; never substitute an API key.",
      "key": "hubSignature",
      "type": "string",
      "value": ""
    },
    {
      "description": "Machine-to-machine x-hub-timestamp value covered by the HMAC signature. Empty in this committed collection.",
      "key": "hubTimestamp",
      "type": "string",
      "value": ""
    }
  ]
}