DIdistru
Credit

Get credits

Changed on

List store credits held by your customers, newest first (by creation datetime, then id). A credit is an amount a customer can apply toward what they owe; each row carries its live computed status and remaining_balance.

Only credits belonging to your company are returned; soft-deleted credits are excluded. Filter by customer (company_ids), by brand (brand_ids, include_no_brand), by the invoices a credit has been applied to (invoice_ids), by amount range, by source, status, credit_number, or the creation/last-modified windows. All filters below are combined with AND — a credit must match every filter you send.

This endpoint returns eventually consistent data: a credit you just created, updated, canceled, or deleted (and any change to its status/remaining_balance) can take up to 1 second to be reflected here.

Required permission: credits_permissions_view. Only credits the authenticated user can access under their team restrictions are returned.

get/public/v1/credits

Request

  • Base URL
    https://app.distru.com
  • Auth
    HTTP bearer

Query parameters

idsstring[]

Restrict the result to specific credits by ID (the same ID returned as each credit's id). Repeat the bracketed key once per ID. Unknown IDs simply match nothing; an empty list is treated as no filter. At most 200 IDs may be given.

amountstring

Filter by the credit's current amount as an inclusive min,max decimal range separated by a comma. Either bound may be omitted: 100, keeps credits of 100 or more, ,500 those of 500 or less, 100,500 those in between. A range with both bounds empty is rejected.

brand_idsstring[]

Restrict to credits for specific brands by company ID (the same ID returned as each credit's brand.id). Repeat the bracketed key once per ID; matches ANY. Combine with include_no_brand=true to also keep credits without a brand. Unknown IDs match nothing; an empty list is no filter. At most 200 IDs.

company_idsstring[]

Restrict to credits held by specific customers by company ID (the same ID returned as each credit's company.id). Repeat the bracketed key once per ID; matches ANY. Unknown IDs match nothing; an empty list is no filter. At most 200 IDs.

credit_numberstring

Case-insensitive substring match on the credit number (partial matches count; e.g. 100 matches CR-1001).

include_no_brandboolean

When true, keep credits that have no brand. Alone it returns only credits without a brand; with brand_ids it returns credits for those brands OR without a brand. Omitted or false applies no brand-less filter.

invoice_idsstring[]

Restrict to credits that have been applied to any of the given invoices by invoice ID (a credit is applied to an invoice through its credit uses; the applied invoice is visible under each credit's credit_uses[].payment.invoice.id, except that payment is null when your team can't see that invoice). Repeat the bracketed key once per ID; matches ANY. Credits never applied to one of these invoices are excluded. Unknown IDs match nothing; an empty list is no filter. At most 200 IDs.

owner_idsstring[]

Restrict to credits owned by any of these Distru users (each credit's owner.id). Repeat the bracketed key once per ID; matches ANY. Unknown IDs match nothing; an empty list is no filter. At most 200 IDs.

inserted_datetimestring

Filter by creation datetime as an ISO8601 after,before range separated by a comma. Either bound may be left empty for an open-ended range: 2022-07-10T00:00:00Z, means on or after that instant, ,2022-07-10T00:00:00Z means on or before it. Both sides empty is rejected.

pagestring

Page selector. Page size is fixed by the server; paginate by following the next_page URL in each response rather than building page selectors yourself — it is null on the last page. next_page uses page[after]=<cursor>, an opaque token marking where the next page resumes; pass it back exactly as given, and only to the endpoint that issued it. This is seek-based, so every page stays fast no matter how deep you page.

source'INVOICE_PAYMENT' | 'QB_CREDIT_MEMO' | 'QB_PAYMENT' | 'RETURN' | 'USER'

Filter by how the credit was created (SCREAMING_CASE): USER (added by hand), RETURN (generated from a return), INVOICE_PAYMENT (an invoice overpayment in Distru), QB_PAYMENT / QB_CREDIT_MEMO (originated in QuickBooks Online). Exact match.

status'ACTIVE' | 'CANCELED' | 'REDEEMED'

Filter by the credit's live computed status (SCREAMING_CASE): ACTIVE (has a remaining balance still to spend), REDEEMED (fully applied, nothing left), CANCELED (voided; its balance can no longer be applied). Exact match.

updated_datetimestring

Filter by last-modified datetime as an ISO8601 after,before range, same comma format as inserted_datetime. Either bound may be empty for an open-ended range.

Response

A list of credits

next_pagestring

URL for the next page of results; null when there is no next page

Example response

{
  "data": [
    {
      "brand": {
        "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c",
        "name": "Retailer 1"
      },
      "company": {
        "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c",
        "name": "Retailer 1"
      },
      "credit_uses": [
        {
          "payment": {
            "company": {
              "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c",
              "name": "Retailer 1"
            }
          }
        }
      ],
      "payment": {
        "company": {
          "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c",
          "name": "Retailer 1"
        }
      },
      "return": {
        "company": {
          "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c",
          "name": "Retailer 1"
        }
      }
    }
  ]
}

Changes

  • d5cbdfacb3c9Revision changes
    • info

      added the non-success response with the status

  • e8b3a3d07ad5Revision changes
    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status