Activities API

Use the Activities API to list the financial activities for a user. Activities are records for all payments, currency transfers, money conversions, requests for payments, and promises of payments. To filter or limit the size of the list, you can specify one or more query parameters. For more information, see the Activities Integration Guide.

Activities (resource group)

Use the /activities resource to list activities.

List activities

GET /v1/activities/activities
Lists activities. To filter or limit the size of the list, you can specify one or more query parameters.

Query parameters

  • start_time

    string

    Filters the list by a time range. The start_time is the lower bound of the time range in Internet date and time format. The start_time cannot be greater than one year before the end_time.

    Default: end_time value minus 30 days.

  • end_time

    string

    Filters the list by a time range. The end_time is the upper bound of the time range in Internet date and time format.

    Default: current time.

  • next_page_token

    number

    The zero-relative start index of the list of items in the response. So, the combination of next_page_token=1 and page_size=20 returns the first 20 items.
  • page_size

    integer

    The number of items to return in the list. The maximum value is 150.

    Default: 30.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/activities/activities?start_time=2012-01-01T00:00:01.000Z&end_time=2014-10-01T23:59:59.999Z&page_size=10 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that lists activities.

Sample Response

{
  "items": [
    {
      "extensions": {
        "payment_properties": {
          "debit_credit_code": "CREDIT"
        }
      },
      "status": "COMPLETED",
      "subtype": "REFUND",
      "gross": {
        "currency_code": "JPY",
        "value": "5000"
      },
      "counterparty": {
        "email": "buyer@example.com",
        "name": "Jennifer McVittie"
      },
      "id": "74M09958P9936162T",
      "fee": {
        "currency_code": "JPY",
        "value": "0"
      },
      "net": {
        "currency_code": "JPY",
        "value": "5000"
      },
      "activity_type": "PAYMENT",
      "time_created": "2013-10-29T22:41:08.000Z"
    },
    {
      "extensions": {
        "payment_properties": {
          "debit_credit_code": "DEBIT"
        }
      },
      "status": "DENIED",
      "subtype": "PAYMENT",
      "gross": {
        "currency_code": "JPY",
        "value": "5000"
      },
      "counterparty": {
        "email": "buyer@example.com",
        "name": "Jennifer McVittie"
      },
      "id": "8B290053Y34018504",
      "fee": {
        "currency_code": "JPY",
        "value": "0"
      },
      "net": {
        "currency_code": "JPY",
        "value": "5000"
      },
      "activity_type": "PAYMENT",
      "time_created": "2013-10-29T22:40:53.000Z"
    },
    {
      "extensions": {
        "payment_properties": {
          "debit_credit_code": "CREDIT"
        }
      },
      "gross": {
        "currency_code": "USD",
        "value": "85.00"
      },
      "counterparty": {
        "name": "PayPal"
      },
      "subtype": "BONUS",
      "status": "COMPLETED",
      "fee": {
        "currency_code": "USD",
        "value": "0.00"
      },
      "net": {
        "currency_code": "USD",
        "value": "85.00"
      },
      "id": "6YH431316S832112L",
      "time_created": "2017-04-18T03:31:54.000Z"
    }
  ]
}

Common object definitions

activity

  • id

    string

    required

    The PayPal-generated ID for the activity.
  • time_created

    string

    required

    The date and time when the activity was created, in Internet date and time format.
  • activity_type

    enum

    required

    Filters the list by one or more activity types. To separate values, use a comma (,). Value is:
    ValueDescription
    BILLING_AGREEMENTAn agreement for a recurring payment for merchant-provided goods or services.
    INVOICEA bill for merchant-provided goods or services.
    MONEY_REQUESTA request for money from one party to another.
    ORDERAn approved purchase without any hold on the funds.
    PAYMENTA movement of money from one account to another.
    PAYOUTA merchant-initiated simultaneous payment to multiple accounts. Typically a commission, rebate, reward, or general disbursement.
    RECURRING_PROFILEA recurring profile.
    SUBSCRIPTIONA subscription.

    Possible values: PAYMENT, MONEY_REQUEST, ORDER, PAYOUT, BILLING_AGREEMENT, INVOICE, SUBSCRIPTION, RECURRING_PROFILE.

  • subtype

    enum

    Filters the list by one or more activity subtypes. Valid only when the activity type is PAYMENT or BILLING_AGREEMENT. To separate values, use a comma (,).
    • For the PAYMENT type, value is:
      ValueDescription
      ADJUSTMENTMovement of funds between accounts by PayPal to resolve a chargeback or dispute.
      AUTHORIZATIONAuthorized hold of funds by PayPal on a customer’s account.
      BONUSPayPal-funded reward or award to a customer's account.
      CORRECTIONAddition or removal of funds by PayPal.
      CURRENCY_TRANSFERConversion of funds from one currency to another.
      HOLDPayment is under review by PayPal.
      HOLDING_BALANCE_TRANSFERTransfer of funds from a main PayPal balance account to another PayPal balance account.
      LOANPayPal credit offered to the seller.
      MONEY_TRANSFERTransfer of funds from a customer's PayPal account to another funding instrument.
      PAYMENTPayment of funds from one entity to another.
      PAYPAL_CREDIT_PAYMENTCustomer repayment of PayPal-provided credit.
      REFUNDReceiver-returned payment to the sender, sender-canceled payment, or unclaimed payment within 30 days.
      REVERSALPayPal-initiated return of funds to sender.
      VOIDCustomer-placed authorization or order that no longer applies.
    • For the BILLING_AGREEMENT type, value is:
      ValueDescription
      SUBSCRIPTION_CANCELLATIONBilling agreement is cancelled.
      SUBSCRIPTION_COMPLETIONBilling agreement is complete.
      SUBSCRIPTION_CREATIONBilling agreement is created.
      SUBSCRIPTION_MODIFICATIONBilling agreement is modified.

    Possible values: PAYMENT, AUTHORIZATION, MONEY_TRANSFER, HOLDING_BALANCE_TRANSFER, BONUS, PAYABLE, PAYPAL_CREDIT_PAYMENT, REFUND, REVERSAL, CURRENCY_TRANSFER, HOLD, RECURRING_PAYMENT_PROFILE, SUBSCRIPTION_CREATION, SUBSCRIPTION_COMPLETION, SUBSCRIPTION_MODIFICATION, SUBSCRIPTION_CANCELLATION, VOID, ADJUSTMENT, CORRECTION, LOAN, DEFAULT, ALL.

  • status

    enum

    Filters the list by one or more activity statuses. To separate values, use a comma (,). Value is:
    ValueDescription
    BLOCKEDA non-allowed activity. The payment violates regulations or compliance rules.
    CANCELEDAn initiator-canceled transaction.
    COMPLETEDA successful transaction.
    CREATEDA successfully created transaction.
    DENIEDA sender-initiated payment that a recipient denies.
    Note: PayPal credits the funds to the sender’s account.
    FAILEDA failed transaction.
    HELDA temporarily-held transaction.
    Note: Because a sender disputes or PayPal reviews the transaction, it is temporarily held.
    PAIDA paid invoice or money request.
    PARTIALLY_PAIDA partially-paid transaction.
    PARTIALLY_REFUNDEDA partially-refunded transaction.
    PENDINGAn in-process payment.
    REFUNDEDA merchant-initiated refund to a customer.
    REVERSEDA PayPal-canceled transaction.
    UNCLAIMEDAn unclaimed payment. A recipient did not accept or receive a sender’s payment.
    Note: PayPal automatically cancels unclaimed transactions after 30 days and credits the funds to the sender’s account.

    Possible values: BLOCKED, CREATED, CANCELED, COMPLETED, DENIED, FAILED, PAID, HELD, PENDING, REFUNDED, PARTIALLY_PAID, REVERSED, PARTIALLY_REFUNDED, UNCLAIMED.

  • counterparty

    object

    The transaction's counter-party. A single-party transaction does not have counter-party information. For example, a single-party transaction might be a currency transfer or a PayPal credit payment.
  • fee

    object

    The PayPal fees that are associated with this activity, in money format.
  • gross

    object

    The amount for this activity before fees are applied.
  • net

    object

    The amount for this activity after fees are applied.
  • partner_fee

    object

    The partner fees, in money format.
  • extensions

    object

    The extension properties.

activity_results

activity_status

  • activity_status

    enum

    Filters the list by one or more activity statuses. To separate values, use a comma (,). Value is:
    ValueDescription
    BLOCKEDA non-allowed activity. The payment violates regulations or compliance rules.
    CANCELEDAn initiator-canceled transaction.
    COMPLETEDA successful transaction.
    CREATEDA successfully created transaction.
    DENIEDA sender-initiated payment that a recipient denies.
    Note: PayPal credits the funds to the sender’s account.
    FAILEDA failed transaction.
    HELDA temporarily-held transaction.
    Note: Because a sender disputes or PayPal reviews the transaction, it is temporarily held.
    PAIDA paid invoice or money request.
    PARTIALLY_PAIDA partially-paid transaction.
    PARTIALLY_REFUNDEDA partially-refunded transaction.
    PENDINGAn in-process payment.
    REFUNDEDA merchant-initiated refund to a customer.
    REVERSEDA PayPal-canceled transaction.
    UNCLAIMEDAn unclaimed payment. A recipient did not accept or receive a sender’s payment.
    Note: PayPal automatically cancels unclaimed transactions after 30 days and credits the funds to the sender’s account.

    Possible values: BLOCKED, CREATED, CANCELED, COMPLETED, DENIED, FAILED, PAID, HELD, PENDING, REFUNDED, PARTIALLY_PAID, REVERSED, PARTIALLY_REFUNDED, UNCLAIMED.

activity_subtype

  • activity_subtype

    enum

    Filters the list by one or more activity subtypes. Valid only when the activity type is PAYMENT or BILLING_AGREEMENT. To separate values, use a comma (,).
    • For the PAYMENT type, value is:
      ValueDescription
      ADJUSTMENTMovement of funds between accounts by PayPal to resolve a chargeback or dispute.
      AUTHORIZATIONAuthorized hold of funds by PayPal on a customer’s account.
      BONUSPayPal-funded reward or award to a customer's account.
      CORRECTIONAddition or removal of funds by PayPal.
      CURRENCY_TRANSFERConversion of funds from one currency to another.
      HOLDPayment is under review by PayPal.
      HOLDING_BALANCE_TRANSFERTransfer of funds from a main PayPal balance account to another PayPal balance account.
      LOANPayPal credit offered to the seller.
      MONEY_TRANSFERTransfer of funds from a customer's PayPal account to another funding instrument.
      PAYMENTPayment of funds from one entity to another.
      PAYPAL_CREDIT_PAYMENTCustomer repayment of PayPal-provided credit.
      REFUNDReceiver-returned payment to the sender, sender-canceled payment, or unclaimed payment within 30 days.
      REVERSALPayPal-initiated return of funds to sender.
      VOIDCustomer-placed authorization or order that no longer applies.
    • For the BILLING_AGREEMENT type, value is:
      ValueDescription
      SUBSCRIPTION_CANCELLATIONBilling agreement is cancelled.
      SUBSCRIPTION_COMPLETIONBilling agreement is complete.
      SUBSCRIPTION_CREATIONBilling agreement is created.
      SUBSCRIPTION_MODIFICATIONBilling agreement is modified.

    Possible values: PAYMENT, AUTHORIZATION, MONEY_TRANSFER, HOLDING_BALANCE_TRANSFER, BONUS, PAYABLE, PAYPAL_CREDIT_PAYMENT, REFUND, REVERSAL, CURRENCY_TRANSFER, HOLD, RECURRING_PAYMENT_PROFILE, SUBSCRIPTION_CREATION, SUBSCRIPTION_COMPLETION, SUBSCRIPTION_MODIFICATION, SUBSCRIPTION_CANCELLATION, VOID, ADJUSTMENT, CORRECTION, LOAN, DEFAULT, ALL.

activity_type

  • activity_type

    enum

    Filters the list by one or more activity types. To separate values, use a comma (,). Value is:
    ValueDescription
    BILLING_AGREEMENTAn agreement for a recurring payment for merchant-provided goods or services.
    INVOICEA bill for merchant-provided goods or services.
    MONEY_REQUESTA request for money from one party to another.
    ORDERAn approved purchase without any hold on the funds.
    PAYMENTA movement of money from one account to another.
    PAYOUTA merchant-initiated simultaneous payment to multiple accounts. Typically a commission, rebate, reward, or general disbursement.
    RECURRING_PROFILEA recurring profile.
    SUBSCRIPTIONA subscription.

    Possible values: PAYMENT, MONEY_REQUEST, ORDER, PAYOUT, BILLING_AGREEMENT, INVOICE, SUBSCRIPTION, RECURRING_PROFILE.

counterparty

  • email

    string

    The other party's email address. For unregistered users only.
  • phone_number

    string

    The other party's mobile phone number.
  • name

    string

    The other party's name, which is usually the first and last name or the merchant's store name.

currency_code

debit_credit_code

  • debit_credit_code

    enum

    Filters the transactions in the list by whether the transaction moves money into or out of a PayPal account. Value is:
    • CREDIT. Includes transactions that move money into a PayPal account.
    • DEBIT. Includes transactions that move money out of a PayPal account.
    • ALL. Includes all transactions.

    Possible values: DEBIT, CREDIT, ALL.

extensions

  • payment_properties

    object

    The properties for a payment activity.
  • request_money_properties

    object

    The money request activity.
  • invoice_properties

    object

    The invoice activity properties.
  • order_properties

    object

    The order activity-specific properties.

invoice_properties

  • role

    object

    The invoice role.
  • invoice_number

    string

    The merchant-provided invoice number for the transaction.

money

  • currency_code

    string

    required

    The three-character ISO-4217 currency code that identifies the currency.

    Minimum length: 3.

    Maximum length: 3.

  • value

    string

    required

    The value, which might be:
    • An integer for currencies like JPY that are not typically fractional.
    • A decimal fraction for currencies like TND that are subdivided into thousandths.
    For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    Maximum length: 32.

    Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

order_properties

  • role

    object

    Filters the list by one or more roles. To separate values, use a comma (,).

payment_properties

  • debit_credit_code

    enum

    Filters the transactions in the list by whether the transaction moves money into or out of a PayPal account. Value is:
    • CREDIT. Includes transactions that move money into a PayPal account.
    • DEBIT. Includes transactions that move money out of a PayPal account.
    • ALL. Includes all transactions.

    Possible values: DEBIT, CREDIT, ALL.

  • buyer_notes

    string

    The sender message for the transaction.
  • order_id

    string

    The ID of the order.
  • billing_agreement_id

    string

    The ID of the billing agreement.
  • subtype_external

    enum

    Filters the list by one or more external subtypes. To separate values, use a comma (,). If you include this parameter, the API ignores the subtype parameter.

    Possible values: UNKNOWN, PURCHASE, MERCHANDISE_RETURN, CASH_WITHDRAWAL, CASH_DEPOSIT, DEBIT_TRANSFER, CREDIT_TRANSFER, DEBIT_PAYMENT, CREDIT_PAYMENT, PURCHASE_WITH_CASHBACK.

  • invoice_number

    string

    The merchant ID for the transaction.

request_money_properties

  • role

    enum

    Filters the list by one or more roles. To separate values, use a comma (,).

    Possible values: REQUESTER, REQUESTEE, PAYER, PAYEE.

role

  • role

    enum

    Filters the list by one or more roles. To separate values, use a comma (,).

    Possible values: REQUESTER, REQUESTEE, PAYER, PAYEE.

subtype_external

  • subtype_external

    enum

    Filters the list by one or more external subtypes. To separate values, use a comma (,). If you include this parameter, the API ignores the subtype parameter.

    Possible values: UNKNOWN, PURCHASE, MERCHANDISE_RETURN, CASH_WITHDRAWAL, CASH_DEPOSIT, DEBIT_TRANSFER, CREDIT_TRANSFER, DEBIT_PAYMENT, CREDIT_PAYMENT, PURCHASE_WITH_CASHBACK.

Additional API information

Error messages

In addition to common HTTP status codes that the REST APIs return, the Activities API can return the following errors.

  • INTERNAL_SERVICE_ERROR

    An internal service error has occurred. A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server.

  • PERMISSION_DENIED

    No permission for the requested operation. The requested operation could not be completed because the caller does not have the correct permission.

  • VALIDATION_ERROR

    Invalid request - see details. A validation error occurred.