:doc:`MarketplaceMetering <../../meteringmarketplace>` / Client / batch_meter_usage

*****************
batch_meter_usage
*****************



.. py:method:: MarketplaceMetering.Client.batch_meter_usage(**kwargs)

  

  .. warning::

    

    The ``CustomerIdentifier`` and ``CustomerAWSAccountID`` are mutually exclusive parameters. You must use one or the other, but not both in the same API request. For new implementations, we recommend using the ``CustomerAWSAccountID``. Your current integration will continue to work. When updating your implementation, consider migrating to ``CustomerAWSAccountID`` for improved integration.

     

   

  To post metering records for customers, SaaS applications call ``BatchMeterUsage``, which is used for metering SaaS flexible consumption pricing (FCP). Identical requests are idempotent and can be retried with the same records or a subset of records. Each ``BatchMeterUsage`` request is for only one product. If you want to meter usage for multiple products, you must make multiple ``BatchMeterUsage`` calls.

   

  Usage records should be submitted in quick succession following a recorded event. Usage records aren't accepted 6 hours or more after an event.

   

  ``BatchMeterUsage`` can process up to 25 ``UsageRecords`` at a time, and each request must be less than 1 MB in size. Optionally, you can have multiple usage allocations for usage data that's split into buckets according to predefined tags.

   

  ``BatchMeterUsage`` returns a list of ``UsageRecordResult`` objects, which have each ``UsageRecord``. It also returns a list of ``UnprocessedRecords``, which indicate errors on the service side that should be retried.

   

  For Amazon Web Services Regions that support ``BatchMeterUsage``, see `BatchMeterUsage Region support <https://docs.aws.amazon.com/marketplace/latest/APIReference/metering-regions.html#batchmeterusage-region-support>`__.

   

  .. note::

    

    For an example of ``BatchMeterUsage``, see `BatchMeterUsage code example <https://docs.aws.amazon.com/marketplace/latest/userguide/saas-code-examples.html#saas-batchmeterusage-example>`__ in the *Amazon Web Services Marketplace Seller Guide*.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/meteringmarketplace-2016-01-14/BatchMeterUsage>`_  


  **Request Syntax**
  ::

    response = client.batch_meter_usage(
        UsageRecords=[
            {
                'Timestamp': datetime(2015, 1, 1),
                'CustomerIdentifier': 'string',
                'Dimension': 'string',
                'Quantity': 123,
                'UsageAllocations': [
                    {
                        'AllocatedUsageQuantity': 123,
                        'Tags': [
                            {
                                'Key': 'string',
                                'Value': 'string'
                            },
                        ]
                    },
                ],
                'CustomerAWSAccountId': 'string'
            },
        ],
        ProductCode='string'
    )
    
  :type UsageRecords: list
  :param UsageRecords: **[REQUIRED]** 

    The set of ``UsageRecords`` to submit. ``BatchMeterUsage`` accepts up to 25 ``UsageRecords`` at a time.

    

  
    - *(dict) --* 

      A ``UsageRecord`` indicates a quantity of usage for a given product, customer, dimension and time.

       

      Multiple requests with the same ``UsageRecords`` as input will be de-duplicated to prevent double charges.

      

    
      - **Timestamp** *(datetime) --* **[REQUIRED]** 

        Timestamp, in UTC, for which the usage is being reported.

         

        Your application can meter usage for up to six hours in the past. Make sure the ``timestamp`` value is not before the start of the software usage.

        

      
      - **CustomerIdentifier** *(string) --* 

        The ``CustomerIdentifier`` is obtained through the ``ResolveCustomer`` operation and represents an individual buyer in your application.

        

      
      - **Dimension** *(string) --* **[REQUIRED]** 

        During the process of registering a product on Amazon Web Services Marketplace, dimensions are specified. These represent different units of value in your application.

        

      
      - **Quantity** *(integer) --* 

        The quantity of usage consumed by the customer for the given dimension and time. Defaults to ``0`` if not specified.

        

      
      - **UsageAllocations** *(list) --* 

        The set of ``UsageAllocations`` to submit. The sum of all ``UsageAllocation`` quantities must equal the Quantity of the ``UsageRecord``.

        

      
        - *(dict) --* 

          Usage allocations allow you to split usage into buckets by tags.

           

          Each ``UsageAllocation`` indicates the usage quantity for a specific set of tags.

          

        
          - **AllocatedUsageQuantity** *(integer) --* **[REQUIRED]** 

            The total quantity allocated to this bucket of usage.

            

          
          - **Tags** *(list) --* 

            The set of tags that define the bucket of usage. For the bucket of items with no tags, this parameter can be left out.

            

          
            - *(dict) --* 

              Metadata assigned to an allocation. Each tag is made up of a ``key`` and a ``value``.

              

            
              - **Key** *(string) --* **[REQUIRED]** 

                One part of a key-value pair that makes up a ``tag``. A ``key`` is a label that acts like a category for the specific tag values.

                

              
              - **Value** *(string) --* **[REQUIRED]** 

                One part of a key-value pair that makes up a ``tag``. A ``value`` acts as a descriptor within a tag category (key). The value can be empty or null.

                

              
            
        
        
    
      - **CustomerAWSAccountId** *(string) --* 

        The ``CustomerAWSAccountID`` parameter specifies the AWS account ID of the buyer.

        

      
    

  :type ProductCode: string
  :param ProductCode: **[REQUIRED]** 

    Product code is used to uniquely identify a product in Amazon Web Services Marketplace. The product code should be the same as the one used during the publishing of a new product.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'Results': [
              {
                  'UsageRecord': {
                      'Timestamp': datetime(2015, 1, 1),
                      'CustomerIdentifier': 'string',
                      'Dimension': 'string',
                      'Quantity': 123,
                      'UsageAllocations': [
                          {
                              'AllocatedUsageQuantity': 123,
                              'Tags': [
                                  {
                                      'Key': 'string',
                                      'Value': 'string'
                                  },
                              ]
                          },
                      ],
                      'CustomerAWSAccountId': 'string'
                  },
                  'MeteringRecordId': 'string',
                  'Status': 'Success'|'CustomerNotSubscribed'|'DuplicateRecord'
              },
          ],
          'UnprocessedRecords': [
              {
                  'Timestamp': datetime(2015, 1, 1),
                  'CustomerIdentifier': 'string',
                  'Dimension': 'string',
                  'Quantity': 123,
                  'UsageAllocations': [
                      {
                          'AllocatedUsageQuantity': 123,
                          'Tags': [
                              {
                                  'Key': 'string',
                                  'Value': 'string'
                              },
                          ]
                      },
                  ],
                  'CustomerAWSAccountId': 'string'
              },
          ]
      }
      
    **Response Structure**

    

    - *(dict) --* 

      Contains the ``UsageRecords`` processed by ``BatchMeterUsage`` and any records that have failed due to transient error.

      
      

      - **Results** *(list) --* 

        Contains all ``UsageRecords`` processed by ``BatchMeterUsage``. These records were either honored by Amazon Web Services Marketplace Metering Service or were invalid. Invalid records should be fixed before being resubmitted.

        
        

        - *(dict) --* 

          A ``UsageRecordResult`` indicates the status of a given ``UsageRecord`` processed by ``BatchMeterUsage``.

          
          

          - **UsageRecord** *(dict) --* 

            The ``UsageRecord`` that was part of the ``BatchMeterUsage`` request.

            
            

            - **Timestamp** *(datetime) --* 

              Timestamp, in UTC, for which the usage is being reported.

               

              Your application can meter usage for up to six hours in the past. Make sure the ``timestamp`` value is not before the start of the software usage.

              
            

            - **CustomerIdentifier** *(string) --* 

              The ``CustomerIdentifier`` is obtained through the ``ResolveCustomer`` operation and represents an individual buyer in your application.

              
            

            - **Dimension** *(string) --* 

              During the process of registering a product on Amazon Web Services Marketplace, dimensions are specified. These represent different units of value in your application.

              
            

            - **Quantity** *(integer) --* 

              The quantity of usage consumed by the customer for the given dimension and time. Defaults to ``0`` if not specified.

              
            

            - **UsageAllocations** *(list) --* 

              The set of ``UsageAllocations`` to submit. The sum of all ``UsageAllocation`` quantities must equal the Quantity of the ``UsageRecord``.

              
              

              - *(dict) --* 

                Usage allocations allow you to split usage into buckets by tags.

                 

                Each ``UsageAllocation`` indicates the usage quantity for a specific set of tags.

                
                

                - **AllocatedUsageQuantity** *(integer) --* 

                  The total quantity allocated to this bucket of usage.

                  
                

                - **Tags** *(list) --* 

                  The set of tags that define the bucket of usage. For the bucket of items with no tags, this parameter can be left out.

                  
                  

                  - *(dict) --* 

                    Metadata assigned to an allocation. Each tag is made up of a ``key`` and a ``value``.

                    
                    

                    - **Key** *(string) --* 

                      One part of a key-value pair that makes up a ``tag``. A ``key`` is a label that acts like a category for the specific tag values.

                      
                    

                    - **Value** *(string) --* 

                      One part of a key-value pair that makes up a ``tag``. A ``value`` acts as a descriptor within a tag category (key). The value can be empty or null.

                      
                
              
            
          
            

            - **CustomerAWSAccountId** *(string) --* 

              The ``CustomerAWSAccountID`` parameter specifies the AWS account ID of the buyer.

              
        
          

          - **MeteringRecordId** *(string) --* 

            The ``MeteringRecordId`` is a unique identifier for this metering event.

            
          

          - **Status** *(string) --* 

            The ``UsageRecordResult`` ``Status`` indicates the status of an individual ``UsageRecord`` processed by ``BatchMeterUsage``.

             

            
            * *Success*- The ``UsageRecord`` was accepted and honored by ``BatchMeterUsage``.
             
            * *CustomerNotSubscribed*- The ``CustomerIdentifier`` specified is not able to use your product. The ``UsageRecord`` was not honored. There are three causes for this result: 

              
              * The customer identifier is invalid.
               
              * The customer identifier provided in the metering record does not have an active agreement or subscription with this product. Future ``UsageRecords`` for this customer will fail until the customer subscribes to your product.
               
              * The customer's Amazon Web Services account was suspended.
              

            
             
            * *DuplicateRecord*- Indicates that the ``UsageRecord`` was invalid and not honored. A previously metered ``UsageRecord`` had the same customer, dimension, and time, but a different quantity.
            

            
      
    
      

      - **UnprocessedRecords** *(list) --* 

        Contains all ``UsageRecords`` that were not processed by ``BatchMeterUsage``. This is a list of ``UsageRecords``. You can retry the failed request by making another ``BatchMeterUsage`` call with this list as input in the ``BatchMeterUsageRequest``.

        
        

        - *(dict) --* 

          A ``UsageRecord`` indicates a quantity of usage for a given product, customer, dimension and time.

           

          Multiple requests with the same ``UsageRecords`` as input will be de-duplicated to prevent double charges.

          
          

          - **Timestamp** *(datetime) --* 

            Timestamp, in UTC, for which the usage is being reported.

             

            Your application can meter usage for up to six hours in the past. Make sure the ``timestamp`` value is not before the start of the software usage.

            
          

          - **CustomerIdentifier** *(string) --* 

            The ``CustomerIdentifier`` is obtained through the ``ResolveCustomer`` operation and represents an individual buyer in your application.

            
          

          - **Dimension** *(string) --* 

            During the process of registering a product on Amazon Web Services Marketplace, dimensions are specified. These represent different units of value in your application.

            
          

          - **Quantity** *(integer) --* 

            The quantity of usage consumed by the customer for the given dimension and time. Defaults to ``0`` if not specified.

            
          

          - **UsageAllocations** *(list) --* 

            The set of ``UsageAllocations`` to submit. The sum of all ``UsageAllocation`` quantities must equal the Quantity of the ``UsageRecord``.

            
            

            - *(dict) --* 

              Usage allocations allow you to split usage into buckets by tags.

               

              Each ``UsageAllocation`` indicates the usage quantity for a specific set of tags.

              
              

              - **AllocatedUsageQuantity** *(integer) --* 

                The total quantity allocated to this bucket of usage.

                
              

              - **Tags** *(list) --* 

                The set of tags that define the bucket of usage. For the bucket of items with no tags, this parameter can be left out.

                
                

                - *(dict) --* 

                  Metadata assigned to an allocation. Each tag is made up of a ``key`` and a ``value``.

                  
                  

                  - **Key** *(string) --* 

                    One part of a key-value pair that makes up a ``tag``. A ``key`` is a label that acts like a category for the specific tag values.

                    
                  

                  - **Value** *(string) --* 

                    One part of a key-value pair that makes up a ``tag``. A ``value`` acts as a descriptor within a tag category (key). The value can be empty or null.

                    
              
            
          
        
          

          - **CustomerAWSAccountId** *(string) --* 

            The ``CustomerAWSAccountID`` parameter specifies the AWS account ID of the buyer.

            
      
    
  
  **Exceptions**
  
  *   :py:class:`MarketplaceMetering.Client.exceptions.InternalServiceErrorException`

  
  *   :py:class:`MarketplaceMetering.Client.exceptions.InvalidProductCodeException`

  
  *   :py:class:`MarketplaceMetering.Client.exceptions.InvalidUsageDimensionException`

  
  *   :py:class:`MarketplaceMetering.Client.exceptions.InvalidTagException`

  
  *   :py:class:`MarketplaceMetering.Client.exceptions.InvalidUsageAllocationsException`

  
  *   :py:class:`MarketplaceMetering.Client.exceptions.InvalidCustomerIdentifierException`

  
  *   :py:class:`MarketplaceMetering.Client.exceptions.TimestampOutOfBoundsException`

  
  *   :py:class:`MarketplaceMetering.Client.exceptions.ThrottlingException`

  
  *   :py:class:`MarketplaceMetering.Client.exceptions.DisabledApiException`

  