청구서 목록 조회
현재 Stripe Customer의 청구서를 페이지 조회
중국 본토 사용자 안내: 중국 본토 사용자는 https://api.toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://api.toapis.com 을 https://api.toapis.cn 로 바꿔 주세요.
인증, 페이지 처리 및 오류는 시작하기를 참조하세요.
동작
계정의 Stripe 청구서 목록을 반환하여 청구와 결제 내역을 대조합니다. 자신의 청구를 조회할 수 있는 것은 메인 계정뿐이며 서브 계정은 HTTP 403, 메인 계정도 본 엔드포인트로 멤버 청구를 조회할 수 없습니다.
기간 내 청구서를 반환하며 기본 최근 31일·최대 366일입니다. 범위는 현재 검증된 Stripe Customer로 제한되며(meta.coverage=current_customer_only) 계정의 전체 이력이 아니고 계정에 연결된 Stripe Customer가 바뀌면 이전 커서가 무효가 되어 첫 페이지부터 다시 조회해야 합니다.
금액은 Stripe 원래 통화의 십진 문자열입니다: USD/CNY는 소수 2자리, JPY는 0자리, KWD는 3자리, ISK/UGX는 소수 2자리를 유지하는 호환 규칙으로 처리됩니다.
subtotal/total은 소계와 합계, amount_due/amount_paid/amount_remaining은 청구액, 지불액, 잔액입니다. 로컬 주문과의 확실한 연결이 없으면 platform_trade_no=null이고 number와 paid_at도 null일 수 있습니다.
Customer ID, 이메일, 주소, 청구서 다운로드 URL, 호스팅 링크는 반환하지 않습니다. 오류 처리: Customer가 없으면 409 (code=15045), Stripe 읽기 실패는 503 (code=15046), 대응 충돌은 503 (code=15047)이며 빈 목록으로 오류를 가리지 않습니다.
청구서는 Stripe 측 데이터로 로컬 입금 기록과는 다릅니다.
인증
Authorizationstring헤더필수Bearer YOUR_SYSTEM_ACCESS_TOKEN 을 사용합니다. 모델 API 키는 사용할 수 없습니다. X-User-Id 는 필요하지 않습니다.
요청 매개변수
fromstring쿼리시간대가 포함된 RFC 3339 시작 시각. 해당 시각을 포함하며 to 와 함께 지정합니다.
제약: date-time.
tostring쿼리시간대가 포함된 RFC 3339 종료 시각. 해당 시각을 제외하며 from 보다 늦어야 합니다.
제약: date-time.
cursorstring쿼리이전 next_cursor 를 그대로 전달하고 필터를 유지합니다. 조건을 변경하면 처음부터 조회합니다.
제약: maxLength=2048.
limitinteger쿼리기본값: 20페이지당 최대 항목 수.
제약: minimum=1; maximum=100; 기본값: 20.
요청 예제
요청 예시
curl --request GET \
--url 'https://api.toapis.com/api/v1/billing/stripe/invoices?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&limit=20' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'import requests
response = requests.get(
"https://api.toapis.com/api/v1/billing/stripe/invoices",
headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
params={
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z",
"limit": "20"
},
timeout=30,
)
response.raise_for_status()
print(response.json())const url = new URL("https://api.toapis.com/api/v1/billing/stripe/invoices");
url.search = new URLSearchParams({
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z",
"limit": "20"
}).toString();
const response = await fetch(url, {
headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());응답 필드
예시는 가상 데이터이며 credits_per_usd="100" 을 가정합니다. 실제 환산에는 응답 값을 사용하세요.
결과는 data.items 에 있습니다. has_more 와 next_cursor 로 페이지를 조회합니다. 마지막 커서는 null 이며 총 개수는 반환하지 않습니다.
codeinteger결과 코드. 0 은 성공입니다.
messagestring성공 시 빈 문자열이며 오류 메시지는 현지화됩니다.
dataobject현재 조회의 결과 객체입니다.
data.itemsobject[]현재 페이지의 기록 목록이며 빈 결과는 [] 입니다.
data.items[].idstring청구서 상세 조회에 사용하는 Stripe 청구서 ID 입니다.
data.items[].providerstring결제 서비스 제공자입니다. 고정 값: "stripe".
data.items[].numberstring | nullStripe 청구서 번호이며 청구서 ID 와 다릅니다. 불명확하거나 해당하지 않으면 null 입니다.
data.items[].statusstringStripe 가 반환한 청구서 상태입니다.
data.items[].created_atstring | null생성 시각입니다. 시간대가 포함된 RFC 3339 형식입니다. 불명확하거나 해당하지 않으면 null 입니다.
data.items[].currencystring금액에 사용되는 원래 통화입니다.
data.items[].subtotalstring청구서 소계이며 통화는 currency 입니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다.
data.items[].totalstring청구서 총액이며 통화는 currency 입니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다.
data.items[].amount_duestring청구서 납부 금액이며 통화는 currency 입니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다.
data.items[].amount_paidstring청구서 납부 완료 금액이며 통화는 currency 입니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다.
data.items[].amount_remainingstring청구서 미납 잔액이며 통화는 currency 입니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다.
data.items[].paid_atstring | nullStripe 에 기록된 청구서 결제 완료 시각입니다. 시간대가 포함된 RFC 3339 형식입니다. 불명확하거나 해당하지 않으면 null 입니다.
data.items[].platform_trade_nonull신뢰할 수 있는 로컬 충전 주문 번호이며 연결 미확인 시 null 입니다.
data.has_moreboolean다음 페이지가 있는지 나타냅니다.
data.next_cursorstring | null동일한 필터로 cursor 에 그대로 전달합니다. 마지막 페이지는 null 입니다.
data.metaobject데이터 출처, 조회 범위 및 집계 기준 등의 메타데이터입니다.
data.meta.sourcestring데이터 출처입니다. 로컬 설정이나 원장 스냅샷은 실시간 Stripe 상태를 뜻하지 않습니다.
data.meta.coveragestring현재 검증된 Stripe Customer 만 포함하며 전체 이력이 아닙니다.
data.meta.scopestring조회 데이터의 소유 범위이며 인증된 계정 자신입니다.
data.meta.fetched_atstring현재 Stripe 조회 시각이며 청구서 생성 시각이 아닙니다.
data.meta.fromstring조회 시간 범위의 시작 시각을 포함합니다.
data.meta.tostring조회 시간 범위의 종료 시각은 제외합니다.
응답 예제
응답 예시
{
"code": 0,
"message": "",
"data": {
"items": [
{
"id": "in_example_01",
"provider": "stripe",
"number": "EXAMPLE-0001",
"status": "paid",
"created_at": "2026-11-01T08:00:00Z",
"currency": "USD",
"subtotal": "10",
"total": "10",
"amount_due": "10",
"amount_paid": "10",
"amount_remaining": "0",
"paid_at": "2026-11-01T08:01:00Z",
"platform_trade_no": null
}
],
"has_more": false,
"next_cursor": null,
"meta": {
"source": "stripe",
"coverage": "current_customer_only",
"scope": "self",
"fetched_at": "2026-11-02T01:00:00Z",
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z"
}
}
}