Payments / Client / batch_get_financial_record
batch_get_financial_record¶
- Payments.Client.batch_get_financial_record(**kwargs)¶
Retrieves up to 100 financial records in one request, including the details that are specific to each record’s type. Identify each record by its ID or by its invoice ID. Results can be partial: each key that you request appears once in the response, either as a record in
financialRecordsor as an error inerrors. A key that matches no record on your account is returned inerrorsand doesn’t fail the request. This operation provides strongly consistent reads.To use this operation, you must have Amazon Web Services Identity and Access Management (IAM) permission for both
payments:BatchGetFinancialRecordandpayments:GetPaymentStatus.See also: AWS API Documentation
Request Syntax
response = client.batch_get_financial_record( keys=[ { 'identifier': 'string', 'invoiceIdentifier': 'string' }, ] )
- Parameters:
keys (list) –
[REQUIRED]
The keys of the financial records to retrieve. Each key is either the record’s ID or its invoice ID.
(dict) –
A way to identify a financial record. Specify exactly one member: the ID that Amazon Web Services Payments issued, in
identifier, or the invoice ID that Amazon Web Services Invoicing issued, ininvoiceIdentifier. If you specify both or neither, the request fails withValidationException.Note
This is a Tagged Union structure. Only one of the following top level keys can be set:
identifier,invoiceIdentifier.identifier (string) –
The ID that Amazon Web Services Payments issued for the record.
invoiceIdentifier (string) –
The invoice ID that Amazon Web Services Invoicing issued for an invoice or a credit memo.
- Return type:
dict
- Returns:
Response Syntax
{ 'financialRecords': [ { 'id': 'string', 'type': 'INVOICE'|'CREDIT_MEMO', 'businessUnit': { 'merchantOfRecord': 'string', 'lineOfBusiness': 'AWS_CLOUD_SERVICES'|'PROSERVE_MARKETING_AND_TRAINING'|'AWS_MARKETPLACE' }, 'amount': { 'value': 'string', 'currency': 'string' }, 'balances': { 'outstanding': { 'value': 'string', 'currency': 'string' }, 'processing': { 'value': 'string', 'currency': 'string' }, 'settled': { 'value': 'string', 'currency': 'string' }, 'canceled': { 'value': 'string', 'currency': 'string' } }, 'settlementStatus': 'OPEN'|'CLOSED', 'status': 'OUTSTANDING'|'PROCESSING'|'SETTLED'|'CANCELED', 'issuedAt': datetime(2015, 1, 1), 'closedAt': datetime(2015, 1, 1), 'details': { 'invoiceDetails': { 'invoiceId': 'string', 'dueStatus': 'DUE'|'PAST_DUE', 'billingPeriod': { 'startDate': datetime(2015, 1, 1), 'endDate': datetime(2015, 1, 1) }, 'dueDate': datetime(2015, 1, 1), 'paymentTerms': 'string', 'invoiceFrequency': 'ONE_TIME'|'RECURRING' }, 'creditMemoDetails': { 'invoiceId': 'string', 'billingPeriod': { 'startDate': datetime(2015, 1, 1), 'endDate': datetime(2015, 1, 1) } } } }, ], 'errors': [ { 'key': { 'identifier': 'string', 'invoiceIdentifier': 'string' }, 'code': 'NOT_FOUND'|'INTERNAL_ERROR', 'message': 'string' }, ] }
Response Structure
(dict) –
financialRecords (list) –
The financial records that the operation retrieved, in no particular order. This list contains fewer records than you requested when
errorsnames one or more keys.(dict) –
An invoice or a credit memo on your account, with the details that are specific to its type.
id (string) –
The ID that Amazon Web Services Payments issued for the record, such as
INV-5364-6253-7364-1342. To retrieve the record again, pass this value toGetFinancialRecordorBatchGetFinancialRecordasidentifier.type (string) –
The type of the financial record. The populated member of
detailsmatches this type. The following values are valid:INVOICE– An invoice: a bill from Amazon Web Services. Payments and credit memos applied to the invoice settle it.CREDIT_MEMO– A credit memo: a credit issued to your account, for example for a billing correction or a service credit. Applying it to one or more invoices settles it.
businessUnit (dict) –
The Amazon Web Services business unit that issued the record: its merchant of record and its line of business.
merchantOfRecord (string) –
The Amazon Web Services entity that issued the invoice and collects payment for it, such as
Amazon Web Services, Inc.orAmazon Web Services EMEA SARL. This is the invoicing entity shown in the Amazon Web Services Billing and Cost Management console. For Amazon Web Services Marketplace purchases, it can differ from the seller of record.lineOfBusiness (string) –
The line of business within the merchant of record that issued the record. This member is absent when the line of business isn’t known for the record. The following values are valid:
AWS_CLOUD_SERVICES– Your usage of Amazon Web Services services.PROSERVE_MARKETING_AND_TRAINING– Amazon Web Services Professional Services, marketing, and training: consulting, events, and training that Amazon Web Services sells.AWS_MARKETPLACE– Products that you bought from sellers in Amazon Web Services Marketplace.
amount (dict) –
The total amount of the financial record, in the currency that the record was issued in. The amount doesn’t change as the record is settled.
balancesshows how much of it is in each settlement state.value (string) –
The amount, as a decimal string, such as
10.99. The number of decimal places can differ between amounts, for example0.0and1000.24.currency (string) –
The ISO 4217 currency code for the amount (for example,
USD).
balances (dict) –
How much of
amountis outstanding, processing, settled, and canceled.outstanding (dict) –
The part of the amount that isn’t settled and has no settlement in progress. For an invoice, this is what remains to pay. For a credit memo, this is the credit that isn’t yet applied. This balance doesn’t include
processing.value (string) –
The amount, as a decimal string, such as
10.99. The number of decimal places can differ between amounts, for example0.0and1000.24.currency (string) –
The ISO 4217 currency code for the amount (for example,
USD).
processing (dict) –
The part of the amount with a settlement in progress, for example a payment that’s submitted but not yet confirmed. It moves to
settledwhen the settlement completes, and back tooutstandingwhen the settlement fails. This balance is more than 0 only when thestatusisPROCESSING.value (string) –
The amount, as a decimal string, such as
10.99. The number of decimal places can differ between amounts, for example0.0and1000.24.currency (string) –
The ISO 4217 currency code for the amount (for example,
USD).
settled (dict) –
The part of the amount that is settled. For an invoice, this is the amount paid or covered by credit memos. For a credit memo, this is the amount applied to invoices. This balance is 0 when nothing is settled yet.
value (string) –
The amount, as a decimal string, such as
10.99. The number of decimal places can differ between amounts, for example0.0and1000.24.currency (string) –
The ISO 4217 currency code for the amount (for example,
USD).
canceled (dict) –
The part of the amount that was canceled and isn’t settled, for example when an invoice is voided. When a partly settled record is canceled, it keeps its
settledbalance, and the rest of the amount moves tocanceled. This balance is more than 0 only when thestatusisCANCELED.value (string) –
The amount, as a decimal string, such as
10.99. The number of decimal places can differ between amounts, for example0.0and1000.24.currency (string) –
The ISO 4217 currency code for the amount (for example,
USD).
settlementStatus (string) –
Whether the record is open or closed. If you receive a
statusvalue that you don’t recognize, use this member to tell open records from closed ones. The following values are valid:OPEN– Part of the amount is outstanding or processing. ThestatusisOUTSTANDINGorPROCESSING.CLOSED– The whole amount is settled or canceled. ThestatusisSETTLEDorCANCELED.
A
CLOSEDrecord becomesOPENagain if a payment or credit applied to it is reversed. ItsclosedAtis then absent until the record closes again.status (string) –
The settlement stage of the record. The following values are valid:
OUTSTANDING– Part of the amount isn’t settled, and no settlement is in progress on the record. For an invoice,dueStatusshows whether it’s due or past due. ThesettlementStatusisOPEN.PROCESSING– A settlement of part or all of the amount is in progress, for example a payment that’s submitted but not yet confirmed.PROCESSINGtakes precedence overOUTSTANDING: while any part of the amount is processing, the status isPROCESSING, even if another part is still outstanding. ThesettlementStatusisOPEN.SETTLED– The whole amount is settled. ThesettlementStatusisCLOSED.CANCELED– The record is canceled. The part of the amount that wasn’t settled isn’t collected or applied. ThesettlementStatusisCLOSED.
issuedAt (datetime) –
The date and time, in UTC, when this record was issued.
closedAt (datetime) –
The date and time, in UTC, when the record was last closed, that is, when its
statuslast becameSETTLEDorCANCELED. This member is absent while thesettlementStatusisOPEN, including after a closed record reopens.details (dict) –
The attributes that exist only for the record’s type. The populated member matches
type:invoiceDetailsfor anINVOICE,creditMemoDetailsfor aCREDIT_MEMO.Note
This is a Tagged Union structure. Only one of the following top level keys will be set:
invoiceDetails,creditMemoDetails. If a client receives an unknown member it will setSDK_UNKNOWN_MEMBERas the top level key, which maps to the name or tag of the unknown member. The structure ofSDK_UNKNOWN_MEMBERis as follows:'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
invoiceDetails (dict) –
The details of an invoice. Populated when
typeisINVOICE.invoiceId (string) –
The invoice ID that Amazon Web Services Invoicing issued for the invoice: the document number printed on it, shown in the Amazon Web Services Billing and Cost Management console and returned by the Amazon Web Services Invoicing API as
InvoiceId.GetFinancialRecordandBatchGetFinancialRecordalso accept it, asinvoiceIdentifier.dueStatus (string) –
Whether the invoice is due or past its due date. This member is present only while the invoice’s
statusisOUTSTANDING. It’s absent when thestatusisPROCESSING,SETTLED, orCANCELED. The following values are valid:DUE– The due date hasn’t passed.PAST_DUE– The due date has passed, and the invoice is still outstanding.
billingPeriod (dict) –
The billing period the invoice covers: the period of the usage it bills.
startDate (datetime) –
The first day of the billing period, inclusive, as the timestamp of 00:00:00 UTC on that day.
endDate (datetime) –
The day after the last day of the billing period, exclusive, as the timestamp of 00:00:00 UTC on that day. A calendar month runs from the first of the month to the first of the next month.
dueDate (datetime) –
The calendar date by which the invoice must be paid, as the timestamp of 00:00:00 UTC on that day. The invoice is past due from the following day.
paymentTerms (string) –
The payment terms for the invoice, as Amazon Web Services Invoicing issued them, such as
Net30. The due date follows from these terms. This member is absent when Amazon Web Services Invoicing didn’t issue payment terms for the invoice.invoiceFrequency (string) –
Whether the invoice was issued once or as part of a billing cycle. The following values are valid:
ONE_TIME– A single invoice that isn’t part of a billing cycle.RECURRING– One invoice of a billing cycle, such as your monthly invoice.
creditMemoDetails (dict) –
The details of a credit memo. Populated when
typeisCREDIT_MEMO.invoiceId (string) –
The invoice ID that Amazon Web Services Invoicing issued for the credit memo: the document number printed on it, shown in the Amazon Web Services Billing and Cost Management console and returned by the Amazon Web Services Invoicing API as
InvoiceId.GetFinancialRecordandBatchGetFinancialRecordalso accept it, asinvoiceIdentifier.billingPeriod (dict) –
The billing period the credit memo applies to: the period of the usage it credits.
startDate (datetime) –
The first day of the billing period, inclusive, as the timestamp of 00:00:00 UTC on that day.
endDate (datetime) –
The day after the last day of the billing period, exclusive, as the timestamp of 00:00:00 UTC on that day. A calendar month runs from the first of the month to the first of the next month.
errors (list) –
The errors for the records that the operation couldn’t retrieve, one for each record, with the key as you requested it and the reason. This list is empty when the operation retrieved every record.
(dict) –
The reason that one of the records requested from
BatchGetFinancialRecordcouldn’t be returned. The other records in the request are unaffected.key (dict) –
The key of the record that couldn’t be retrieved, as you requested it.
Note
This is a Tagged Union structure. Only one of the following top level keys will be set:
identifier,invoiceIdentifier. If a client receives an unknown member it will setSDK_UNKNOWN_MEMBERas the top level key, which maps to the name or tag of the unknown member. The structure ofSDK_UNKNOWN_MEMBERis as follows:'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
identifier (string) –
The ID that Amazon Web Services Payments issued for the record.
invoiceIdentifier (string) –
The invoice ID that Amazon Web Services Invoicing issued for an invoice or a credit memo.
code (string) –
The error code that indicates why the retrieval failed. The following values are valid:
NOT_FOUND– No financial record on your account matches the key.INTERNAL_ERROR– An internal error occurred while processing this record. The other records in the request are unaffected. You can retry this record.
message (string) –
A description of why the operation couldn’t retrieve this record. The wording can change at any time and isn’t localized, so don’t parse this value. To handle the error in your code, use
codeinstead.
Exceptions
Payments.Client.exceptions.InternalServerExceptionPayments.Client.exceptions.ThrottlingExceptionPayments.Client.exceptions.ValidationExceptionPayments.Client.exceptions.AccessDeniedException