:doc:`DeviceFarm <../../devicefarm>` / Client / purchase_offering

*****************
purchase_offering
*****************



.. py:method:: DeviceFarm.Client.purchase_offering(**kwargs)

  

  Immediately purchases offerings for an AWS account. Offerings renew with the latest total purchased quantity for an offering, unless the renewal was overridden. The API returns a ``NotEligible`` error if the user is not permitted to invoke the operation. If you must be able to invoke this operation, contact `aws-devicefarm-support@amazon.com <mailto:aws-devicefarm-support@amazon.com>`__.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/devicefarm-2015-06-23/PurchaseOffering>`_  


  **Request Syntax**
  ::

    response = client.purchase_offering(
        offeringId='string',
        quantity=123,
        offeringPromotionId='string'
    )
    
  :type offeringId: string
  :param offeringId: **[REQUIRED]** 

    The ID of the offering.

    

  
  :type quantity: integer
  :param quantity: **[REQUIRED]** 

    The number of device slots to purchase in an offering request.

    

  
  :type offeringPromotionId: string
  :param offeringPromotionId: 

    The ID of the offering promotion to be applied to the purchase.

    

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

    
    ::

      {
          'offeringTransaction': {
              'offeringStatus': {
                  'type': 'PURCHASE'|'RENEW'|'SYSTEM',
                  'offering': {
                      'id': 'string',
                      'description': 'string',
                      'type': 'RECURRING',
                      'platform': 'ANDROID'|'IOS',
                      'recurringCharges': [
                          {
                              'cost': {
                                  'amount': 123.0,
                                  'currencyCode': 'USD'
                              },
                              'frequency': 'MONTHLY'
                          },
                      ]
                  },
                  'quantity': 123,
                  'effectiveOn': datetime(2015, 1, 1)
              },
              'transactionId': 'string',
              'offeringPromotionId': 'string',
              'createdOn': datetime(2015, 1, 1),
              'cost': {
                  'amount': 123.0,
                  'currencyCode': 'USD'
              }
          }
      }
      
    **Response Structure**

    

    - *(dict) --* 

      The result of the purchase offering (for example, success or failure).

      
      

      - **offeringTransaction** *(dict) --* 

        Represents the offering transaction for the purchase result.

        
        

        - **offeringStatus** *(dict) --* 

          The status of an offering transaction.

          
          

          - **type** *(string) --* 

            The type specified for the offering status.

            
          

          - **offering** *(dict) --* 

            Represents the metadata of an offering status.

            
            

            - **id** *(string) --* 

              The ID that corresponds to a device offering.

              
            

            - **description** *(string) --* 

              A string that describes the offering.

              
            

            - **type** *(string) --* 

              The type of offering (for example, ``RECURRING``) for a device.

              
            

            - **platform** *(string) --* 

              The platform of the device (for example, ``ANDROID`` or ``IOS``).

              
            

            - **recurringCharges** *(list) --* 

              Specifies whether there are recurring charges for the offering.

              
              

              - *(dict) --* 

                Specifies whether charges for devices are recurring.

                
                

                - **cost** *(dict) --* 

                  The cost of the recurring charge.

                  
                  

                  - **amount** *(float) --* 

                    The numerical amount of an offering or transaction.

                    
                  

                  - **currencyCode** *(string) --* 

                    The currency code of a monetary amount. For example, ``USD`` means U.S. dollars.

                    
              
                

                - **frequency** *(string) --* 

                  The frequency in which charges recur.

                  
            
          
        
          

          - **quantity** *(integer) --* 

            The number of available devices in the offering.

            
          

          - **effectiveOn** *(datetime) --* 

            The date on which the offering is effective.

            
      
        

        - **transactionId** *(string) --* 

          The transaction ID of the offering transaction.

          
        

        - **offeringPromotionId** *(string) --* 

          The ID that corresponds to a device offering promotion.

          
        

        - **createdOn** *(datetime) --* 

          The date on which an offering transaction was created.

          
        

        - **cost** *(dict) --* 

          The cost of an offering transaction.

          
          

          - **amount** *(float) --* 

            The numerical amount of an offering or transaction.

            
          

          - **currencyCode** *(string) --* 

            The currency code of a monetary amount. For example, ``USD`` means U.S. dollars.

            
      
    
  
  **Exceptions**
  
  *   :py:class:`DeviceFarm.Client.exceptions.ArgumentException`

  
  *   :py:class:`DeviceFarm.Client.exceptions.NotFoundException`

  
  *   :py:class:`DeviceFarm.Client.exceptions.NotEligibleException`

  
  *   :py:class:`DeviceFarm.Client.exceptions.LimitExceededException`

  
  *   :py:class:`DeviceFarm.Client.exceptions.ServiceAccountException`

  

  **Examples**

  The following example purchases a specific device slot offering.
  ::

    response = client.purchase_offering(
        # You can get the offering ID by using the list-offerings CLI command.
        offeringId='D68B3C05-1BA6-4360-BC69-12345EXAMPLE',
        quantity=1,
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'offeringTransaction': {
            'cost': {
                'amount': 8.07,
                'currencyCode': 'USD',
            },
            'createdOn': datetime(2016, 8, 31, 12, 59, 0, 2, 244, 0),
            'offeringStatus': {
                'type': 'PURCHASE',
                'effectiveOn': datetime(2016, 8, 31, 12, 59, 0, 2, 244, 0),
                'offering': {
                    'type': 'RECURRING',
                    'description': 'Android Remote Access Unmetered Device Slot',
                    'id': 'D68B3C05-1BA6-4360-BC69-12345EXAMPLE',
                    'platform': 'ANDROID',
                },
                'quantity': 1,
            },
            'transactionId': 'd30614ed-1b03-404c-9893-12345EXAMPLE',
        },
        'ResponseMetadata': {
            '...': '...',
        },
    }

  