# Retrieve usage file upload URL

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


This endpoint returns an upload URL for uploading usage events files, allowing you to upload files in supported formats. The file is processed asynchronously, and its status can be tracked using the `[retrieve_file_processing_status](/docs/api/usage_files/get-uploaded-file-processing-status)` endpoint.

Before uploading, review the following guidelines and constraints:

-   [Best practices](/docs/api/usage_files)
-   [File upload constraints](/docs/api/usage_files#file_upload_constraints)
-   [File field constraints](/docs/api/usage_files)
-   [Handling errors](/docs/api/usage_files)

## Sample Request

#### cURL

```bash
curl  https://{site}.file-ingest.chargebee.com/api/v2/usage_files/upload_url \
     -u {site_api_key}:\
     -d file_name="usage_events-1743661346062.csv" \
     -d mime_type="text/csv"
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = UsageFile.UploadUrl()
		.FileName("usage_events-1743661346062.csv")
		.MimeType("text/csv")
		.Request();

UsageFile usageFile = result.UsageFile;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    usagefileAction "github.com/chargebee/chargebee-go/v3/actions/usagefile"
    "github.com/chargebee/chargebee-go/v3/models/usagefile"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := usagefileAction.UploadUrl(&usagefile.UploadUrlRequestParams{
        FileName : "usage_events-1743661346062.csv",
        MimeType : "text/csv",
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        UsageFile := res.UsageFile
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.UsageFileUploadUrlRequest{
    FileName : "usage_events-1743661346062.csv",
    MimeType : "text/csv",
}
  res, err := client.UsageFile.UploadUrl(req)
      if err != nil {
        fmt.Println(err)
    } else {
        UsageFile := res.UsageFile
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = UsageFile.uploadUrl()
            .fileName("usage_events-1743661346062.csv")
            .mimeType("text/csv")
            .request();

        UsageFile usageFile = result.usageFile();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.usageFile.UsageFile;
import com.chargebee.v4.models.usageFile.params.UsageFileUploadUrlParams;
import com.chargebee.v4.models.usageFile.responses.UsageFileUploadUrlResponse;

public class UsageFileUploadUrl {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        UsageFileUploadUrlParams params = UsageFileUploadUrlParams.builder()
            .fileName("usage_events-1743661346062.csv")
            .mimeType("text/csv")
            .build();

        UsageFileUploadUrlResponse response = client.usageFiles().uploadUrl(params);

        UsageFile usageFile = response.getUsageFile();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.usageFile.uploadUrl({
        file_name: "usage_events-1743661346062.csv",
        mime_type: "text/csv"
    });

    console.log(result);
    const usageFile = result.usage_file;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->usageFile()->uploadUrl([
    "file_name" => "usage_events-1743661346062.csv",
    "mime_type" => "text/csv"
]);
$usageFile = $result->usage_file;
```

#### Python

```python
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.UsageFile.upload_url(
    cb_client.UsageFile.UploadUrlParams(
        file_name="usage_events-1743661346062.csv",
        mime_type="text/csv"
    )
)
usage_file = response.usage_file
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::UsageFile.upload_url({
  :file_name => "usage_events-1743661346062.csv",
  :mime_type => "text/csv"
})

usage_file = result.usage_file
```

## Sample Response

```json
{
  "usage_file": {
    "id": "6fa7df05-9d4a-4c29-a161-bded616459c4",
    "name": "usage_events-1743661346062.csv",
    "mime_type": "text/csv",
    "upload_details": {
      "url": "https://cb-prod-us-e1-fileservice-temporaryfiles-store.s3.amazonaws.com/staged_file/{site}/01JR2NJ25PA7WKQCW5G6H0TR99/usage_events-1743661346062.csv?X-Amz-Security-Token=/....",
      "expires_at": 1743662040000
    }
  }
}
```

## URL Format

**POST** https://[site].file-ingest.chargebee.com/api/v2/usage_files/upload_url

## Input Parameters

- `file_name` (required, string, max chars=150)
  Name of the file being uploaded.
  
  **Note:** No special characters are allowed in the `file_name` except for underscores `_` and hyphens `-` .**Example**:
  
  **Valid file name**
  
  **Invalid file name**
  
  merchant\_data.csv
  
  merchant@data.csv
  
  sales\_report-2024.csv
  
  sales&report-2024.csv
  
  customer\_details\_file.csv
  
  customer!details#file.csv

- `mime_type` (required, string, max chars=100)
  Indicates the format of a file.
  
  **Note:** Currently, only `text/csv` is supported.

## Returns

- `usage_file` (Usage file object)
  Resource object representing usage\_file