Payments / Client / get_financial_record

get_financial_record

Payments.Client.get_financial_record(**kwargs)

Retrieves a single financial record, including the details that are specific to its type. Specify exactly one of the following:

  • The ID that Amazon Web Services Payments issued for the record, in identifier.

  • The invoice ID that Amazon Web Services Invoicing issued for an invoice or a credit memo, in invoiceIdentifier.

If you specify both or neither, the request fails with ValidationException. If no record on your account matches, the request fails with ResourceNotFoundException.

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:GetFinancialRecord and payments:GetPaymentStatus.

See also: AWS API Documentation

Request Syntax

response = client.get_financial_record(
    identifier='string',
    invoiceIdentifier='string'
)
Parameters:
  • identifier (string) – The ID that Amazon Web Services Payments issued for the financial record, as returned in id.

  • invoiceIdentifier (string) – The invoice ID that Amazon Web Services Invoicing issued for an invoice or a credit memo. The operation returns the record that has this invoice ID.

Return type:

dict

Returns:

Response Syntax

{
    'financialRecord': {
        '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)
                }
            }
        }
    }
}

Response Structure

  • (dict) –

    • financialRecord (dict) –

      The requested financial record.

      • 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 to GetFinancialRecord or BatchGetFinancialRecord as identifier.

      • type (string) –

        The type of the financial record. The populated member of details matches 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. or Amazon 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. balances shows 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 example 0.0 and 1000.24.

        • currency (string) –

          The ISO 4217 currency code for the amount (for example, USD).

      • balances (dict) –

        How much of amount is 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 example 0.0 and 1000.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 settled when the settlement completes, and back to outstanding when the settlement fails. This balance is more than 0 only when the status is PROCESSING.

          • value (string) –

            The amount, as a decimal string, such as 10.99. The number of decimal places can differ between amounts, for example 0.0 and 1000.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 example 0.0 and 1000.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 settled balance, and the rest of the amount moves to canceled. This balance is more than 0 only when the status is CANCELED.

          • value (string) –

            The amount, as a decimal string, such as 10.99. The number of decimal places can differ between amounts, for example 0.0 and 1000.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 status value 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. The status is OUTSTANDING or PROCESSING.

        • CLOSED – The whole amount is settled or canceled. The status is SETTLED or CANCELED.

        A CLOSED record becomes OPEN again if a payment or credit applied to it is reversed. Its closedAt is 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, dueStatus shows whether it’s due or past due. The settlementStatus is OPEN.

        • PROCESSING – A settlement of part or all of the amount is in progress, for example a payment that’s submitted but not yet confirmed. PROCESSING takes precedence over OUTSTANDING: while any part of the amount is processing, the status is PROCESSING, even if another part is still outstanding. The settlementStatus is OPEN.

        • SETTLED – The whole amount is settled. The settlementStatus is CLOSED.

        • CANCELED – The record is canceled. The part of the amount that wasn’t settled isn’t collected or applied. The settlementStatus is CLOSED.

      • 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 status last became SETTLED or CANCELED. This member is absent while the settlementStatus is OPEN, including after a closed record reopens.

      • details (dict) –

        The attributes that exist only for the record’s type. The populated member matches type: invoiceDetails for an INVOICE, creditMemoDetails for a CREDIT_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 set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:

        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        • invoiceDetails (dict) –

          The details of an invoice. Populated when type is INVOICE.

          • 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. GetFinancialRecord and BatchGetFinancialRecord also accept it, as invoiceIdentifier.

          • dueStatus (string) –

            Whether the invoice is due or past its due date. This member is present only while the invoice’s status is OUTSTANDING. It’s absent when the status is PROCESSING, SETTLED, or CANCELED. 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 type is CREDIT_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. GetFinancialRecord and BatchGetFinancialRecord also accept it, as invoiceIdentifier.

          • 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.

Exceptions